Hi,
The developer guide in my company says class comments should go before Package statements, i.e it sould be the very first thing in a java file.
I just find it a bit old. Isn't it normal practice to put class comments after import and above class declaration?
Puzzled Sarah
Yes typical way normal IDE's would give you by default is to have class comment after imports. But again this is convention and not a rule. You should follow what people around you are accustomed to as this is probably propriety code and need not be done the typical way.
I have never heard of anyone using class javadoc comments before the class declaration. I'm no sure how the JavaDoc tool would handle that.
Sun officially recommends putting it right before the class.
A doc comment is written in HTML and must precede a class, field, constructor or method declaration.
My interpretation of the above is that a comment describing a class that does not immediately precede the class declaration is incorrect.
In most companies that I have worked in, the part before "package" will only contain copyright notices and disclaimers, for legal rather than technical reasons. Something about putting all disclaimers before someone had a chance to view any content. This is common practice. Most developers skim that part of the code, and many IDEs will auto-insert this legalese.
The only organizations in which I have seen module level documentation before java "packages" are ones that are traditionally C++ organizations, where putting description at the beginning of an H file is more common.
All that being said, coding practices are just a recommendation. The unfortunate reality of mandated practices that do not make sense is that someone in power believes they know better. They might not appreciate mere mortals questioning them.
If you want to try and convince them otherwise, run the JavaDoc tool and examine the generated files. If there are no class-level comments, you have a good argument that you might win.
I would say that is down right wrong. What are we supposed to do in these cases?
/**
* Does this even work?
*/
package a.b.c;
class SomeClass {
/**
* Where else should I put this?
*/
private static class SomeInnerClass {
}
}
/**
* Ok, maybe this is unnecessary.
*/
class SomeOtherClass {
/**
* Some other stuff.
*/
private static class SomeOtherInnerClass {
}
}
One could say that having more than one top level class in one .java file should be avoided, but there are legitimate cases you wan to have an inner class.
Perhaps they are referring to file comments (which are not processed by the JavaDoc document generator).
It's not uncommon to see the copyright/license information here.
Sometimes people just put the actual file name, and file creation date here (I believe this is the default for some IDEs), though I don't really see the point of this (I sort of see why you'd document the file creation date, but not really).