Re: Commenting code

[Ray Blaak <blaak@infomatch.com>]

Roedy Green <roedy@mindprod.com> writes:
> There a philosophical problem that Jonathan Revusky and I have tussled
> over.  When writing JavaDoc, should it be complete, or should it
> contain only unexpected information?

It should only contain the unexpected information. Let the code describe
itself as much as possible, as you pointed out.

> 
> "getZipPlusFive  get the US Zip+5 postal code."
> 
> If you add this sort of comment, you just needlessly create typing.
> You pad the source, diluting the true information.
> 
> However, if you leave it out entirely, someone just perusing the
> JavaDoc instead of the method signatures themselves, is missing vital
> information.

This works for me:

  public PostalCode getZipPlusFive(PostalCode zipCode);

When perusing java code or its documentation, missing the method signatures
themselves seems completely nonsensical to me. 

Are not the signatures always present even in JavaDoc generated pages?

One cannot reliably understand an interface otherwise.

> Perhaps then, you could document just the parameter, with no comment.

Only if the parameter name and type do not adequately describe themselves.

> The problem with this is, how do you tell a "boring" void entry from
> one yet to be done? That too could lead to invalid assumptions.

My rule is: don't repeat what the code says. This is my canonical bad example:

  /**
   * Does a particular thing.
   *
   * @parm someInput - some input
   * @exception InvalidInput raised when the input is invalid
   * @return the result
   */
  public Result doParticularThing(Input someInput) throws InvalidInput

this is ok:

  public Result doParticularThing(Input someInput) throws InvalidInput

this is too:

  /**
   * @exception InvalidInput when someInput is null or not blah blah
   * @return a valid result or null when blah blah
   */
  public Result doParticularThing(Input someInput) throws InvalidInput

That is, comments describe things not intuitively available from the code.

-- 
Cheers,                                        The Rhythm is around me,
                                               The Rhythm has control.
Ray Blaak                                      The Rhythm is inside me,
blaak@infomatch.com                            The Rhythm has my soul.