Re: On Comments
Peter Duniho wrote:
On Wed, 21 May 2008 21:14:48 -0700, Kenneth P. Turvey
<kt-usenet@squeakydolphin.com> wrote:
[...]
Comments are important in code. In particular, header comments
describing the method, its inputs and outputs, and any assumptions it
makes, are really, _REALLY_, important.
True. But it's important to remember that too many comments is also
bad. Comments are only needed to elaborate non-obvious things.
Ideally, even for complex code, the code itself can represent the
information needed.
I think the OP was trying to stress interface documentation. For
example, although `void setProperty(String name, String value)' seems
obvious, a comment like the following wouldn't be a bad idea:
/*
[ ... ]
NOTE: The following function merely sets the property to the given value
in the local cache. Most importantly, it does not reify said value to
the database for purposes of batching changes.
External consumers of this code may impose certain additional
requirements not listed here. So beware that setting the following
property incorrectly may result in errors in later processing code.
[ ... ]
*/
[ Note: an actual comment ]
On the other hand, this is just bad:
// This actually means we have an inbox
attribute canGetMessages;
Good names for variables, structuring the code using common idioms, etc.
can go a long way. And every comment you can avoid is a comment that
doesn't have to be maintained: a big problem with comments is that it's
possible to change the code without changing the comment, and the code
will still work fine. But the comment will now mislead anyone trying to
figure out the code, or even possibly lead someone to believe that the
code is wrong, at which time they "fix" it, breaking everything.
This is true for implementation but not interfaces. While most
setRandomProperty() stuff tends to be documented along the lines of
"sets random property", sometimes nuances not reflected in the short
name needs to be detailed in-depth in the comments on the set/get
properties. For example, see my example above.
Comments can also be used to denote blocks of functions with similar
purposes in large ('000s of lines) files. I've also used them to denote
warnings that the code is not fully correct for various reasons or when
I'm using code that is hackish or even for simple elided statements:
next(); // Consume '<'
--
Beware of bugs in the above code; I have only proved it correct, not
tried it. -- Donald E. Knuth