Robin:
How can we hope to have reasonable conversations when people are arguing
against comments. I don't know where they work but I've seen millions of
lines of code and I'm sure each programmer thought the code was completely
clear when in fact it was plainly not. What seems obvious as it is being
written won't be so obvious 3 years later when 8 of the original programmers
have quit. But let's say I include a SSort() routine, would developers
recognize it as a "stable sort" just by reading the code? I'll guess that
90% of the VB programmers haven't heard of a stable sort so how can they
recognize one? I'll also guess "what a dork doesn't he know there is a sort
method" is what some of the folks here would say.
But that is only one use of comments. They have been elevated in status
through the use of things like JavaDoc (in Java). In large apps I've seen
3, 4 and 5 versions of "identical functionality" simply because none of the
programmers knew the other functions existed when they wrote their own local
version. An automated system for producing printed documentation would go a
long way to reducing this stuff.
We also use them to track changes. With business critical apps (and I mean
daily or weekly turnaround schedules) it is important to know what changed,
who changed it, when it was changed and why it was changed. There is no
more sensible place to put this information than next to the code that
actually changed. And if you made a undocumented modification and the $14
million a year client dropped the company because your change ruined their
system you can bet there would be repercussions.
They aren't fun, and the system isn't perfect but how on Earth can anybody
be arguing against commenting? I suspect it's a game... the "your code is
inferior because you have to comment it" gambit. But my code isn't inferior
it is as good or better and it has reasonable and useful comments as well.
These types of threads come about continually, it's part of the coming of
age of software developers. I've had programmers (who "knew" they were the
greatest) tell me that programmers don't read documentation. When I
challenged that statement he asked if I thought the majority of programmers
read the docs and I answered, "no not the majority, just the good ones."
Well that's my 2 cents... everybody carry on