Re: Canonical Comments
Roedy Green wrote:
At the head of each program you can use /* // or /** comments.
You can place them before the package, before the import, before the
class.
Except Javadoc only picks up doc comments in the last case.
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html>
<http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html>
You want to get such information in there as: author, version, what the
class does, copyright, version history.
It would be a good thing if all programs did this the same way. How do
you think it should done?
"A foolish consistency is the hobgoblin of little minds." - R. W. Emerson
Martin Gregorie wrote:
For myself, I use:
/**
* comment
*/
between imports and class and in front of every method. AFAICR javadocs
doesn't like comments in front of imports.
The Javadoc docs say:
Placement of comments - Documentation comments are recognized
only when placed immediately before class, interface, constructor,
method, or field declarations
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html#documentationcomments>
/*
comment
*/
inside methods as private notes to developers. I don't use javadoc-
accessible comments inside methods because it's hard to make the result
read nicely.
And Javadoc doesn't see them anyway.
Martin Gregorie wrote:
// comment
I personally hate this style - so call me old fashioned. It reminds me
It's got nothing to do with old- versus new-fashioned. These are for one-line
comments, typically end-of-line comments like:
if ( condition ) // set by foo method
To use or not use them is utterly a matter of choice.
too much of assembler. I only use it to temporarily comment out code if
I'm trying alternative logic and don't want to lose the previous pearls
of wisdom. The comment-out code is always removed before I move on.
I'm lazier than I should be about using annotations. I tend to describe
method arguments in the body of the method-level comment rather than use
@parameter annotation.
That's no annotation of which I've heard. Perhaps you are referring to the
'@param' Javadoc tag? Javadoc tags are not annotations.
A tag is a special keyword within a doc comment that
the Javadoc tool can process.
<http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html#javadoctags>
I generate javadocs, read the result and edit the comments until I'm
satisfied that they read well before I release code.
Excellent practice.
When starting a new module, I write the class-level comment at the same
time as the declaration. Similarly, the method-level comment is written
together with the method declaration.
Modern IDEs will generate the core of that for you in the new-code template.
As to Roedy's point, I put a /* comment block at the top of the file, before
the package directive, with file name, repository keywords and the like. I
put Javadoc comments in the places where Javadoc comments go. I recommend
against using the Javadoc '@version' tag for internal version information,
such as the source-control system generates, but to use it for the public
version of the entire library.
--
Lew