Anyone who claims that the source code is enough documentation for any programmer is really fooling
himself and doing more harm than good. If I had a choice between source code and documentation, I
would pick source code, because at least it's possible to glean the documentaion from the source, but
not the other way around.
I heartily agree with the first part. I'm not
sure about the second: given a good description
of what the code is supposed to do, it's usually
fairly easy to write the actual code.
One problem with programming classes is that they
teach you to write code that compiles, but they
don't teach you how to comment. Here are some of
the habits I've picked up regarding comments:
Start by writing the comments. Say what
the code is going to do. Read your comments.
Make sure you're doing the right thing.
If there's something that needs to be done
to the code, but not just yet, or you're not sure
how to do it, add an XXX or FIXME comment, e.g.:
You can find the "XXX" or "FIXME" comments with
grep. If you don't put them in now, you'll
never remember to fix the problem later.
When you're adding a new function, add a
descriptive comment at the top, even if you're
in a hurry. This comment should list, at least:
The range of acceptable inputs (if the
function takes a char *, is it okay
to give it a NULL? What about a non-NULL, but
empty, string?)
What the function does when all goes well.
What the function does when there's an
error.
What assumptions the function makes.
It's amazing how many problems you can avoid
this way.
Perhaps most importantly: we can all read
your source and see what the code does. Your
comments should say what it should do.
This also serves as an error-correction mechanism:
if the code and the comments don't agree, then
there's obviously a problem.
Finally, write the sorts of comments you
wish the code had. You'll make the next person
to read the code happy. As likely as not, that
person will be you.
Speaking as the leader on an open source project
of my own
(ColdSync), one of the things you might want
to do after you submit a change to a project is
to take a look at the next release and see what
happened to your submission.
While I accept patches from all sorts of people,
they rarely make it into the source as-is: I do
exercise editorial control. A lot of times, the patch I receive will omit
something like error-checking, or else it doesn't
quite fit in with what I'm planning to do with
the code.
Sometimes I get submissions from
newbies with good ideas, bot who make some
mistakes. When I find these, I either try to fix
them, or at least add an XXX comment to the code.
In any case, of course, the submitter gets full
credit for the patch.
wouldn't this make a terrific tool for the disabled? just come up with a brailey(sp) like code and all a
blind person would have to do is move the mouse over the lines of text and he's reading it...
Absolutely, though probably not in the way you
describe. Braille involves patterns of dots; a
mouse pointer really only represents a single
point, so what you describe would presumably be
like reading braille with a toothpick (or, for
a sighted person, having a 1x1 pixel monitor).
You could use the mouse as a "spotlight" onto an
interesting area, and have some OCR tool translate
the text into speech or something. But this
doesn't require a force-feedback mouse.
The interesting thing about this mouse, IMHO, is
that it might allow blind people to use
off-the-shelf GUIs more easily. Most X window
managers allow you to attach sounds to events
such as entering/leaving a window, pulling down
a menu, etc. Presumably these can now be
complemented with textures attached to window
borders, buttons, separators between menu items,
etc.
Most online documents and software packages are
not specifically designed for blind users (though
they are spared the horror of the <BLINK>
tag and flashing banner ads).
``Here's your copy of Emacspeak. It's extremely
powerful, and millions of people swear by it.
What's that? You'd rather use WordPerfect? Gee,
I guess you're out of luck.''
A low-level tool that allows people to use any
high-level software package would be a major
goodism.
Open-source software does help expose deliberately placed backdoors, however, it does not target the problem that caused the Microsoft flaw in the first place: untrustworthy programmers. No project, closed source or open source, run under the cathedral model or the bazaar model, can escape the fundemental concept of information security: you must place at least some implicit trust on the people who build/mantain/administer your software.
You are correct. When I install the latest version of a compiler for my users, I have to trust the authors, the people who run the ftp site whence I got it, and so forth. My users have to trust me.
What openness does is to reduce the level of trust you must place in anyone. If I don't trust the person who built an RPM, I can fetch an SRPM from somewhere else, or just get the source from the original author. If I have doubts about the source, I can read it. If I don't have the skill to read the source and find problems, I can read Bugtraq and see if anyone else has found any problems.
Likewise, in my work as a sysadmin, I am held accountable by the fact that all of my users and coworkers can also read the source or Bugtraq, if they want to take the time to do so. They also know where I work, so if they really get mad at me, they can come after me with torches and Frankenstein rakes.
The way I read ESR's article is that in the OSS world, no such problem would have remained undetected for four years, at least not in a widely-used package.
In the closed-source world, you have to trust the authors and distributors of the software. They may be the most honest and intelligent people in the world, but you still have to trust them: there aren't many mechanisms for finding out whether your trust is misplaced.
A group of programmers were presenting a report to the Emperor. "What was the greatest achievement of the year?" the Emperor asked.
The programmers spoke among themselves and then replied, "We fixed 50% more bugs this year than we fixed last year."
The Emperor looked on them in confusion. It was clear that he did not know what a "bug" was. After conferring in low undertones with his chief minister, he turned to the programmers, his face red with anger. "You are guilty of poor quality
control. Next year there will be no 'bugs'!" he demanded.
And sure enough, when the programmers presented their report to the Emperor the next year, there was no mention of bugs.
Explain to management that a machine's name is different from what it does. It might make sense to name your primary database server "SQL1", but two years down the road, it'll be too old and feeble to do any serious database work, and you'll put it on someone's desk to read mail with. Then that person will wind up with a workstation named SQL1, which is bogus.
Machines (and their names) come and go. Use CNAME records to indicate a machine's functionality. Make "SQL1" a CNAME that points to "Goofy" today, and "Cyclops" tomorrow after you upgrade.
Re:Unix is Unix is Unix
on
Which BSD?
·
· Score: 1
Actually, AIX becomes a lot more tolerable if you stop pretending that it's Unix, and recognize it as a species of its own.
I don't think that *BSD is significantly easier or harder to learn than Linux. They're both descendents of the grand Unix tradition, so it's not surprising that they have a lot in common.
I think the main thing you need to do, if you haven't done so already, is to realize that Unix and Windows are completely different entities. Once you reconcile yourself to the fact that you'll need to learn a new OS from scratch, you'll be fine. Also, as a rule, Unix is a lot more configurable, but that comes at the price of complexity. As an analogy, think of Windows as a car: you can specify what color you want it, whether you want automatic or manual transmission, and whether you want the extended warranty. Unix, on the other hand, is a box of Legos: you're handed a box of parts, and you can put them together any way you like. Yes, this is more complex, but you can do much more.
Personally, I'm a BSD bigot, probably because I grew up on a VAX running 4.2BSD, so I'd love to see you run *BSD (probably FreeBSD, since it tends to be the most featureful of the *BSDs on Intel boxes). However, from what I've seen, Caldera's OpenLinux is the most newbie-friendly of the free OSes.
If you're just starting out, I'd say that FreeBSD, Red Hat Linux and Caldera OpenLinux are approximately equal (within an order of magnitude) in terms of complexity. I'd recommend that you try at least two of them and see which one(s) you like best.
Slashdot Mirror
One problem with programming classes is that they teach you to write code that compiles, but they don't teach you how to comment. Here are some of the habits I've picked up regarding comments:
You can find the "XXX" or "FIXME" comments with grep. If you don't put them in now, you'll never remember to fix the problem later.
- The range of acceptable inputs (if the
function takes a char *, is it okay
to give it a NULL? What about a non-NULL, but
empty, string?)
- What the function does when all goes well.
- What the function does when there's an
error.
- What assumptions the function makes.
It's amazing how many problems you can avoid this way.While I accept patches from all sorts of people, they rarely make it into the source as-is: I do exercise editorial control. A lot of times, the patch I receive will omit something like error-checking, or else it doesn't quite fit in with what I'm planning to do with the code.
Sometimes I get submissions from newbies with good ideas, bot who make some mistakes. When I find these, I either try to fix them, or at least add an XXX comment to the code.
In any case, of course, the submitter gets full credit for the patch.
Absolutely, though probably not in the way you describe. Braille involves patterns of dots; a mouse pointer really only represents a single point, so what you describe would presumably be like reading braille with a toothpick (or, for a sighted person, having a 1x1 pixel monitor).
You could use the mouse as a "spotlight" onto an interesting area, and have some OCR tool translate the text into speech or something. But this doesn't require a force-feedback mouse.
The interesting thing about this mouse, IMHO, is that it might allow blind people to use off-the-shelf GUIs more easily. Most X window managers allow you to attach sounds to events such as entering/leaving a window, pulling down a menu, etc. Presumably these can now be complemented with textures attached to window borders, buttons, separators between menu items, etc.
Most online documents and software packages are not specifically designed for blind users (though they are spared the horror of the <BLINK> tag and flashing banner ads). ``Here's your copy of Emacspeak. It's extremely powerful, and millions of people swear by it. What's that? You'd rather use WordPerfect? Gee, I guess you're out of luck.''
A low-level tool that allows people to use any high-level software package would be a major goodism.
You are correct. When I install the latest version of a compiler for my users, I have to trust the authors, the people who run the ftp site whence I got it, and so forth. My users have to trust me.
What openness does is to reduce the level of trust you must place in anyone. If I don't trust the person who built an RPM, I can fetch an SRPM from somewhere else, or just get the source from the original author. If I have doubts about the source, I can read it. If I don't have the skill to read the source and find problems, I can read Bugtraq and see if anyone else has found any problems.
Likewise, in my work as a sysadmin, I am held accountable by the fact that all of my users and coworkers can also read the source or Bugtraq, if they want to take the time to do so. They also know where I work, so if they really get mad at me, they can come after me with torches and Frankenstein rakes.
The way I read ESR's article is that in the OSS world, no such problem would have remained undetected for four years, at least not in a widely-used package.
In the closed-source world, you have to trust the authors and distributors of the software. They may be the most honest and intelligent people in the world, but you still have to trust them: there aren't many mechanisms for finding out whether your trust is misplaced.
Explain to management that a machine's name is different from what it does. It might make sense to name your primary database server "SQL1", but two years down the road, it'll be too old and feeble to do any serious database work, and you'll put it on someone's desk to read mail with. Then that person will wind up with a workstation named SQL1, which is bogus.
Machines (and their names) come and go. Use CNAME records to indicate a machine's functionality. Make "SQL1" a CNAME that points to "Goofy" today, and "Cyclops" tomorrow after you upgrade.
Actually, AIX becomes a lot more tolerable if you stop pretending that it's Unix, and recognize it as a species of its own.
I don't think that *BSD is significantly easier or harder to learn than Linux. They're both descendents of the grand Unix tradition, so it's not surprising that they have a lot in common.
I think the main thing you need to do, if you haven't done so already, is to realize that Unix and Windows are completely different entities. Once you reconcile yourself to the fact that you'll need to learn a new OS from scratch, you'll be fine. Also, as a rule, Unix is a lot more configurable, but that comes at the price of complexity. As an analogy, think of Windows as a car: you can specify what color you want it, whether you want automatic or manual transmission, and whether you want the extended warranty. Unix, on the other hand, is a box of Legos: you're handed a box of parts, and you can put them together any way you like. Yes, this is more complex, but you can do much more.
Personally, I'm a BSD bigot, probably because I grew up on a VAX running 4.2BSD, so I'd love to see you run *BSD (probably FreeBSD, since it tends to be the most featureful of the *BSDs on Intel boxes). However, from what I've seen, Caldera's OpenLinux is the most newbie-friendly of the free OSes.
If you're just starting out, I'd say that FreeBSD, Red Hat Linux and Caldera OpenLinux are approximately equal (within an order of magnitude) in terms of complexity. I'd recommend that you try at least two of them and see which one(s) you like best.