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.
There are two possible meanings for "non-obvious" here, and it matters a
lot which one you mean:
1. Not obvious to someone who is trying to find out e.g. how to make a
particular change as rapidly as possible, and wants to read as little
code as possible to achieve that.
2. Not obvious to someone who is already familiar with all the other
methods in the application.
Code in Java tends to be a string of method and constructor calls. If
each one is properly documented, it can be understood quite quickly
working with two windows, one viewing the code and the other viewing the
Javadoc output. If information is missing from the header comments, it
can mean constant working up and down a stack, reading one method just
to understand another method that needs to be understood to read the
relevant code.
Patricia