Re: Coding Standards

Lew wrote:

While I agree with Matthias's points about commenting the more obscure
parts of one's code, I cannot believe that he seriously is against the
use of Javadocs.

Javadoc has advantages and disadvantages. The most prominent advantage
is of course automated generation of reference documentation, however,
I've found that the major disadvantage is that with javadoc comments,
source code tends to get filled with some kind of textual styrofoam.
.

Relevant Pages

  • Re: Coding Standards
    ... Constructor description ... So far its worked out pretty well, resulting in Javadoc output that reads nicely and manages to avoid the creation of separate documentation that must be maintained. ... I agree with Lew about commenting the code: if a method is just inline statements then the method description is all that's needed, but more complex code can benefit from having descriptive comments dropped into it. ...
    (comp.lang.java.programmer)
  • Re: Canonical Comments
    ... I have to agree with Lew that this is something that does not need to be standardized. ... The Javadoc tool has its own spec, ... /** goes before the class declaration as specified by the Javadoc documentation. ...
    (comp.lang.java.programmer)