Canonical Comments

[Roedy Green]

At the head of each program you can use /* // or /** comments.

You can place them before the package, before the import, before the
class.

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?

--
Roedy Green Canadian Mind Products
http://mindprod.com

For most people, a global average temperature rise of 3°C (5°F) does not sound
alarming. They don’t understand that the warming is uneven, mostly over the
continents which will rise 6°C (11°F). The maximum annual temperature will
increase considerably more. Paris will have the temperature of Algiers,
Moscow the temperature of Paris, San Francisco the temperature of Tijuana and
New York the temperature of Charleston, and Houston the temperature of some
obscure dusty town in southern Mexico.

 

[Martin Gregorie]

At the head of each program you can use /* // or /** comments.

You can place them before the package, before the import, before the
class.

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?

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.

/*
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.

// comment
I personally hate this style - so call me old fashioned. It reminds me
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.

I generate javadocs, read the result and edit the comments until I'm
satisfied that they read well before I release code.

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.

 

[Qu0ll]

At the head of each program you can use /* // or /** comments.

You can place them before the package, before the import, before the
class.

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?

I put a file header before the package statement using /* */ comments that
includes the company name, the license, copyright and file-related symbols
for the version control system. I then use /** */ comments above the class
itself that includes the description of the class, the author(s) and version
symbols for the version control system. Version history is for the SCM, not
the source file.

It makes no sense to put class information, authors and version at the top
of the file as one file may contain more than one class.

I don't think there needs to be a "standard" for this sort of thing. All
that matters is that all the relevant information is there and it's in a
readable form.

--
And loving it,

-Qu0ll (Rare, not extinct)
_________________________________________________
(e-mail address removed)
[Replace the "SixFour" with numbers to email me]

 

[Arved Sandstrom]

I put a file header before the package statement using /* */ comments
that includes the company name, the license, copyright and file-related
symbols for the version control system. I then use /** */ comments
above the class itself that includes the description of the class, the
author(s) and version symbols for the version control system. Version
history is for the SCM, not the source file.

With respect to the last sentence, depends on what you mean by version.
If you mean VCS version (like a Subversion revision) I agree with you.
But if it's a logical version, as in "this file is version 1.0", the
file itself is a good place to put that information. Ultimately _that_
version is set by humans, and in any case unless you've got high-powered
SCM software you'll have to edit it in yourself.

It makes no sense to put class information, authors and version at the
top of the file as one file may contain more than one class.

As regards authorship, version control systems and other comments
capture that information better anyway.

I don't think there needs to be a "standard" for this sort of thing.
All that matters is that all the relevant information is there and it's
in a readable form.

I agree with that.

AHS

 

[Arne Vajhøj]

At the head of each program you can use /* // or /** comments.

You can place them before the package, before the import, before the
class.

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?

You decide and you follow the decision.

If you lack good ideas, then following:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182
would not be the worst thing to do.

Arne

 

[JannaB]

/**
* Definitely should be in the manner that facillitates javadocs. In
world of unit testing young * nazis, why do they NOT take
advantage of this. I'm ok with /*...*/ to rem out multiple lines
* in lieu of using // for more than one contiguous line, but if any
remarks ARE required for
* good programming practice it is these -- so we can use your code
with just the javadocs!
*/

//Janna

 

[Martin Gregorie]

And Javadoc doesn't see them anyway.

Didn't it used to do that? I have hazy memories of trying it and finding
the result so difficult to prettify that I walked away fast. Ditto
comments about public attributes and public final constants.

In any case I take pains to use the method-level comment to describe the
purpose of the method, its arguments and (sometimes) when and how to use
it. They specifically do NOT say anything about its inner workings. The
comments in the method body are there to tell a programmer what he needs
to know and should be of no concern to anybody else.

To use or not use them is utterly a matter of choice.

Sure - that's personal. I find end-of-line comments are fine in assembler
or any other languages where the code itself naturally forms a tall, thin
column down the page, but generally become clutter if used in block
structured languages or COBOL, Fortran, Perl etc. IMO a block of comment
at the start of a logical block or in front of a block of code doing a
relatively complex task stands out better and tends to make the source
easier to read.

Its a writing style I use for private code too: ymmv but I find good
comments are helpful when I come back to my own code a few years after I
last looked at it.

That's no annotation of which I've heard. Perhaps you are referring to
the '@param' Javadoc tag?

That's the one. I don't normally use an IDE - two terminal windows and
ant are generally sufficient - but if I'm using an IDE that generates
@param stubs then I'll complete them rather than ignoring or deleting
them.

Modern IDEs will generate the core of that for you in the new-code
template.

As I said, I normally don't use IDEs because I'm not sure that they offer
anything more than I can get from a good editor (I don't much like the
IntelliJ one - its refactoring etc tools are nice, but its missing a few
straight text editing capabilities that I use a lot.

In any case, I tend to treat the source file for a new class as a module
spec with class and method stubs - I write the spec as a single large
javadoc comment that happens to contain the class declaration and method
stubs and don't start adding code until I'm happy that the spec
adequately describes what I'm about to implement. This, combined with
Wirth's top-down incremental development approach works for me and has
the benefit of allowing the code to be compiled and test run all through
the development process. I've seen a few too many ****-ups and hard-to-
test pieces of code result from doing it in other ways.

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.

Thats an interesting idea. It would be a good place for cvs to inject the
version history too. If you're GPLing code do you put the GPL wording
there or in the first javadoc comment?

 

[Tom Anderson]

/**
* Definitely should be in the manner that facillitates javadocs. In
world of unit testing young * nazis, why do they NOT take
advantage of this. I'm ok with /*...*/ to rem out multiple lines
* in lieu of using // for more than one contiguous line,

Although you supply quite a good example of why not to do that right there
- comments don't nest, so your main comment block accidentally ends just
before "to rem".

tom

 

[Lew]

Thats an interesting idea. It would be a good place for cvs to inject the
version history too.

There is no good place in the source artifact to put the version
history. To put that differently, any place in the source artifact
where you put the version history is a bad place to put it.

If you're GPLing code do you put the GPL wording there or in the first javadoc comment?

That depends on whether you want the license visible to users of the
code or to maintainers only.

 

[Mark Space]

If you're GPLing code do you put the GPL wording
there or in the first javadoc comment?

I would say both.

I think for legal reasons it needs to go at the head of any file. Just
like copyright notices are placed at the beginning of a film or book,
they are placed at the start of a file too.

Also for legal/cya reasons, I'd put a copyright notice in the Javadoc.
First of all, as a derived source, the Javadoc should have the same
license as the source, and the reader must be made aware of it. Second,
it's just a courtesy to let anyone browsing your docs know what license
you are using. It prevents foul-ups and disappointment down the road.

 

[Lew]

Also for legal/cya reasons, I'd put a copyright notice in the Javadoc.
First of all, as a derived source, the Javadoc should have the same
license as the source, and the reader must be made aware of it.  Second,
it's just a courtesy to let anyone browsing your docs know what license
you are using.  It prevents foul-ups and disappointment down the road.

This to my eye is one of the dicier areas of the GPL and copyright
licenses in general.

It seems clear from careful reading of the GPL that the Javadoc HTML
as generated from the source is a "Derived Work" and therefore subject
to the source code license. However, in and of itself the HTML is not
the source code and is a separate work from the point of view of
normal copyright law. Putting the copyright / copyleft license notice
in the Javadoc HTML puts the HTML itself under the license in its own
right, not just as a derived work.

The regular GPL being geared to source code might not be the most
appropriate for the Javadocs /qua/ documentation, for which arguably
the GFDL is more appropriate.
<http://en.wikipedia.org/wiki/GNU_General_Public_License>
<http://en.wikipedia.org/wiki/GNU_Free_Documentation_License>
<http://www.opensource.org/licenses>
<http://www.gnu.org/copyleft/fdl.html>

Assuming you like the Gnu licenses as opposed to, say, the Apache
ones.

 

[Martin Gregorie]

There is no good place in the source artifact to put the version
history. To put that differently, any place in the source artifact
where you put the version history is a bad place to put it.

I don't normally put it in the code, but I sometimes consider it. Then I
lie down until the thought goes away.

That depends on whether you want the license visible to users of the
code or to maintainers only.

So far its gone in the top Javadocs comment. I was wondering if there was
a better place to put it, but it would seem the isn't.

 

[Martin Gregorie]

so we can use your code with just the javadocs!
*/

IMO if you can't understand and use a class from the Javadocs then its
poorly documented. Nobody should need to read the code to use a class,
particularly if its a library class.

I've seen classes released to a project with nothing in the Javadocs
except the method templates and a list of public attributes. We didn't
even *have* that source and method names were short rather than
informative. So, we were reduced to making long phone calls and sending e-
mails to the developer in an attempt to prize words and example code out
of him. He claimed he was short of time, but I bet dealing with these
calls and mails took more time than writing comments would have done.

Seeing crap like this should be a wake-up call to developers to actually
document stuff, but it seems there are still plenty around who are brain
dead when it comes to documentation.

 

[Arved Sandstrom]

There is no good place in the source artifact to put the version
history. To put that differently, any place in the source artifact
where you put the version history is a bad place to put it.

[ SNIP ]

See my other post. I wouldn't maintain an entire version history in the
source file, but I'd certainly consider commenting the latest version in
the source file. After all, if you have versions at all you may have no
other place to put it.

Note that I'm not talking about VCS revision numbers, changeset IDs,
tags or build numbers. I mean the version of the source according to
design/requirements specifications.

AHS

 

[Arne Vajhøj]

I have to agree with Lew that this is something that does not need to be
standardized. The Javadoc tool has its own spec, the rest is programmer
preference.

Too many different styles in a project can give a frustrating read.

Arne

 

[Arne Vajhøj]

I would say both.

I think for legal reasons it needs to go at the head of any file. Just
like copyright notices are placed at the beginning of a film or book,
they are placed at the start of a file too.

I don't think it need to. It is just common practice.

GPL says:

<quote>
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
</quote>

safest != need to

Also for legal/cya reasons, I'd put a copyright notice in the Javadoc.
First of all, as a derived source, the Javadoc should have the same
license as the source,

JavaDoc is not derived source. Derived source would be a modified
version of the Java code.

JavaDoc could be considered object code. It is generated
from the source code.

and the reader must be made aware of it. Second,
it's just a courtesy to let anyone browsing your docs know what license
you are using. It prevents foul-ups and disappointment down the road.

That is a good point.

Arne

 

[Arne Vajhøj]

This to my eye is one of the dicier areas of the GPL and copyright
licenses in general.

It seems clear from careful reading of the GPL that the Javadoc HTML
as generated from the source is a "Derived Work" and therefore subject
to the source code license.

I consider it object code not derived source code.

However, in and of itself the HTML is not
the source code and is a separate work from the point of view of
normal copyright law. Putting the copyright / copyleft license notice
in the Javadoc HTML puts the HTML itself under the license in its own
right, not just as a derived work.

Not much point anyway.

As far as I can the only practical point is that if you give someone
the Java Docs for an app that are under GPL, then you are required
to supply the source code, similar to the rule for binaries (in the case
of Java jar/class files).

And I can not really see that as a problem. Only those that can get
the source or the binaries will be interested in the Java Docs. And
if the author puts the code under GPL, then the author seems interested
in distributing the software.

Arne

 

[Arne Vajhøj]

There is no good place in the source artifact to put the version
history. To put that differently, any place in the source artifact
where you put the version history is a bad place to put it.

I disagree.

It is not unusual to distribute source code in .zip/.tar.gz instead
of via CVS/SVN.

Arne

 

[Martin Gregorie]

Too many different styles in a project can give a frustrating read.

I thought Roedy meant something more widespread than a project, but of
course you're right about standardisation being a good idea for a
project. Almost all commercial projects I've worked on have used a source
template - usually just the comment at the start of the source file - and
along with that have set down coding and naming standards so the various
source files are at least similar to read.

I've also had to critique or work on code collections from other sources.
Most have been written to similar standards, but a few haven't and these
have typically been a mess any way you looked at them: design
documentation, coding standards, and functionally all tended to be poor
an inconsistent.

 

[Mark Space]

<http://en.wikipedia.org/wiki/GNU_Free_Documentation_License>

This is an interesting link. The Wikipedia article lists some of the
requirements of the GFDL, including that revision history be maintained.
I think that's a bit odious for my taste. I doubt I'd want to work on
any docs with that requirement. It's too easy to lose the repository
some how, either accidentally or just recovering disk space when a
project ends. (Or if the mean just a list of edits, well that could be
odious too, not to mention useless to most people.)

In fact, in general I think I stay away from GPL and friends (LGPL is
ok) just because the license is too restrictive in many ways. As you
point out there are easier licenses to work with out there (Apache,
Creative Commons, etc.)