Commenting Issues

["Noel J. Bergman" <no...@devtech.com>]

[Coalescing the NNTP server discussion on commenting]

> IMHO I'd agree that javadocs should only be used on public and package
scope
> methods and fields. [Danny]

I can agree that javadocs MUST be used on public/package scope items.  I
won't say that they MUST NOT be used elsewhere.  I just don't have any
particular cares about the latter.

> Private fields and methods need only be commented, and
> privately, where their use is not clear from the code. [Danny]

Ok, this means that most of them should be commented except for the most
trivial.  However, I am of the mind that comments should be a way of telling
another programmer (or myself, much later), what and why.  Especially the
why.  A comment like:

    item.unlock();	// remove the lock

is worthless.  I can see that we are calling the unlock method.  But a
comment like:

    // spool.remove() has a side-effect!  It unlocks the
    // message so that other threads can work on it!  If
    // we don't remove it, we must unlock it!
    spool.unlock(key);

tells me something important about the operation of the code.

> I subscribe to the XP view that a requirement for extensive commenting of
> sources is in avoidance of writing clear code.  [Danny]

[Personal aside: XP is nothing more than a marketing slick relabeling for
Gen-Xers of tried and true practices, many of which date back 30 years or
more.]

IAE, what is clear to one programmer who knows an RFC inside-out may not be
clear to another.  I put that comment about spooling in for the next person
who wanted to work on that code.  By the time I figured out how spooling
worked, the code would have been "clear" to me (at least for the duration of
that week ;-)).

> Obviously this has to be tempered, in a OS project particularly, with the
> need to make the code accessable to any would be developer  [Danny]

I agree that we must establish the mindset that we at least have to comment
the code as if we were explaining it to another person so that they can make
changes.  Which is, of course, what we're really doing.

This is basically what you and Peter are both agreeing.  As Peter said,
"James developers don't have the benefit of any of these [face-to-face XP]
methodologies [that enhance communication between developers], so commenting
is correspondingly more important as a tool for inter-developer
communication."

> > - Not do javadocs on private methods/variables. There does not really
> > seem to be a gain in javadoc for implementation details. [Harmeet]

> All methods/variables should be documented.  I don't understand
> how you can say there is no gain in javadocing implementation
> details.  [Peter]

Javadocs !== documentation.  Javdocs <= documentation.  He isn't saying that
methods/variables should not be documented.  He's just saying that he
doesn't see the gain of using javadoc tags for private implementation items.

In fact, I could argue that exposing that private members with javadoc tags
is dangerous, on the grounds that implementation details should not be
exposed outside of the source.  We don't want someone to read the javadocs
and make assumptions about implementation.  Only those things that make up
the contract should be javadoc'd.  I'm willing to listen to a contrary view,
but please explain it.

> The primary goal of documentation is to convey an understanding of the
code
> to developers other than the author.  [Peter]

Peter, the good news is that no one appears to be disagreeing about
commenting.  The issue here appears to be only whether or not to use javadoc
tags within the comments for private items.

	--- Noel


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>