I used to work for a software vendor whose policy was "*no comments in code*
".
Usually I'm a real documentation kind of guy. So I was a bit shocked at this
policy, to say the least. And this job was writing C code which doesn't have
a reputation for self-documentation. After working there for awhile, I
gradually began to see the wisdom of their policy. Consider these points:
- Comments can be a crutch. If a programmer is forced to rely solely on the
code, then you tend to make the code more self-documenting. Perhaps instead
of selecting "A", "B" and so on for variable names, you carefully select
meaningful names. Or write the code in a straightforward manner rather than
dazzling with arcane constructions.
- Out-of-date comments can be misleading. People often modify code but fail
to modify the comments.
- Most comments are superfluous, of the variety "the following line sums
the values of A and B and stores the result in C", followed by C = A + B.
Having 7 lines of comment per line of code can end up obscuring the code.
Dennis Williams
--
http://www.freelists.org/webpage/oracle-l
Received on Fri Aug 19 2005 - 10:38:58 CDT
