For additional information :
IMPORTANT
Write the javadoc IMMEDIATELY after the implementation (or simultaneously ) of the method in such a way that there is no warnings. If you postpone it, you will forget it later, or at least not remember the details. Alt + Shift + J in Eclipse generates well formed javadoc, just fill it. Moreover, when a method is edited, the corresponding javadoc should be actualized accordingly. Be diligent in following the rules bellow.
API specification vs API documentation
In the javadoc, programmers should strive to provide full information about the specification of a method - all relevant things it does, preconditions, postconditions and side effects, yet not how it does them. Moreover, there could be documentation details, such as sample usage, but this is left optional to the judgement of the developer.
How to write clear and informative javadoc
Every javadoc comment should start with a clear one sentence description (dot plus breaking space). The javadoc tool includes it in the resume of the method or class. Inability to specify the main idea in one sentence often means poor design.
- Methods: after the first sentence follows precise description of method behavior, effects and side effects, preconditions and postconditions. Javadoc is compulsory for methods with public, protected and package domain, and encouraged for those with private visibility. Some required tags follow in this order: *@param - one for each parameter in the order of appearance in the method declaration. Should be stated what is the parameter meaning, its usage, preconditions about it, whether it is modified or not, if it could be null, etc. *@return - description of the return value, with focus on different return values such as errors or branch scenarios (e.g. when true, when false). *@throws (or @exception - both are equivalent) - one for each checked exception (those that extend from Exception). There should be clearly stated in what cases the exceptions appear. There may be @throws for unchecked exceptions (that extend RuntimeException and Error), but this is not encouraged - only if the developer considers it very important to notify for an unchecked exception. *There could be other tags in the following order (@author - not encouraged in Sophie-JR; @version - repository revision, not encouraged; @see class name; @since tag in which appears, not encouraged; @depracated - nice style is to provide @see or @link tag to the method to be used instead.)
- Classes: brief and informative description of what the class does. There could be also sample usage added. Not tags are compulsory.
- Packages: the javadoc tools copies a "package.html" file that should be in the package directory. It is written in html. Sample template used buy Sun can be found at http://java.sun.com/j2se/javadoc/writingdoccomments/package-template.
- Variables - only for public and package(default) variables, which we do not use! Otherwise (private, protected) - use comments.
Javadoc tool features
- Private inner classes (closures) javadoc comments are not included in the final documentation. If the developer considers documenting such a class import - to document it in the javadoc of the upper class. In such classes comments are encouraged, but not javadoc.
- Inheritance
- @see and @link tags to the parent automatically generated
- @see and @link tags to the parent automatically generated for overriding and methods (including interface method implementation), so there is no need to copy javadoc comments from parent's method to child's method. However, if there is no javadoc documentation for a method, the parent documentation is automatically copied by the tool.
Notes on style
- <code>ClassName</code> may be used when class names or method names are referred.
- "this" keyword (not the, or the object) should be used when referring to the object in use.
- when referring to another method no parentheses should be used (e.g. ...the add method...), except an exact argument list is provided (e.g. ...the add(int x, int y) method...)
- methods description sentence starts with a verb. (e.g. Gets the width of this component.)
- parameter description may be short phrase based (e.g. the x coordinate of this component.) Then additional description follows.
- Since javadoc comments are interpreted to html, all the formating you do is ignored. Formating can be made through valid html tags. The most popular html tags used in the javadoc are: *<"p"> (without the quotes) paragraph - useful in the general description of classes and methods"<"pre"><"/pre"> preformated text - preserves the formating, useful for code same, for example.
Comments
- Maybe it is a good idea to write something like a checklist of clear and concise rules that the developers and the reviewers should follow. --boyan@2009-01-12
