Re: Coding Standards

Lew wrote:
Karl Uppiano wrote:
-- except for JavaDocs, which I write copiously. It gives me a nice place to describe the class, member variable, or method, with the input parameters, return values and exceptions thrown, in a way that is far more structured than you would get with ad-hoc comments.

Matthias Buelow wrote:
Which are exactly the kind of useless comments that clatter source code.
I thought the code should be expressive enough without all that chatter?
Documenting trivial details is nonsense. You should explain the big
picture in comments and why you did some details the way you did them,
and not verbosely reformulate parts of the source code.

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. Javadocs are critical in Java source. They serve double duty - not only do they help future users of a class to use it correctly, they cover most of the non-trivial comments one would make about a class or method (or other exposed member). It's hardly "chatter".

I've been experimenting with writing class specifications as ASCII text files structured as:

Introductory text describing the class and its intended purpose,
limitations, etc.

repeat for all constructors
Constructor description
constructor header
end-repeat

repeat for all public or protected methods
Method description
method header
end-repeat

so that, once I'm happy that the spec is complete, correct, spell-checked and readable it can be turned into self-documented compilable code by adding:

- the class header and block
- turning descriptions into Javadoc comments and inserting HTML
formatting tags etc
- adding minimal blocks behind the constructor and method headers.

Once this has been done its easy to add implementing code and private methods.

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 (but never is).

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. These are always indented to match the code and use /* ... */ delimiters (never /**) because I don't think that this type of comment has any place in the Javadoc method description.


--
martin@ | Martin Gregorie
gregorie. | Essex, UK
org |
.

Relevant Pages

  • Re: Opinions of advice to always define an empty noargs constructor?
    ... takes up space better taken by real code, ... It is best if every public method and constructor has a proper Javadoc ... Automatic behaviour may add some complexity and most of Java is about ...
    (comp.lang.java.programmer)
  • Re: Why can I not use: Math a=new Math();
    ... > Does JavaDoc generate documentation for implicitly created constructors? ... > admit I'm feeling too lazy this AM to check for myself. ... I just tested that and javadoc DOES include the default constructor. ...
    (comp.lang.java.programmer)
  • Re: 7.0 wishlist?
    ... Ok, Javadoc is unnecessary, but for maintenance ... You are stretching the intended semantics of ‘abstract’ here. ... It is not intended to mean ‘this class has a constructor which you may ... Comment: Using GnuPG with SUSE - http://enigmail.mozdev.org ...
    (comp.lang.java.programmer)
  • Re: javadoc Linking Classes
    ... there is no link to the documentation page for the ... > a class in the class c constructor on the c documentation page (where ... > the a class instance is a parameter). ... Run Javadoc on all the classes at the same time, ...
    (comp.lang.java.help)
  • Re: javadoc Linking Classes
    ... there is no link to the documentation page for the ... > a class in the class c constructor on the c documentation page (where ... > the a class instance is a parameter). ... Run Javadoc on all the classes at the same time, ...
    (comp.lang.java.programmer)