Stephen Colebourne's blog: Javadoc coding standards - 0 views
blog.joda.org/...javadoc-coding-standards.html
java javadoc BestPractices documentation design communication
shared by kuni katsuya on 13 Dec 12
- No Cached
-
Javadoc coding standards
-
explain some of the rationale for some of my choices
-
this is more about the formatting of Javadoc, than the content of Javadoc
- ...63 more annotations...
-
Each of the guidelines below consists of a short description of the rule and an explanation
-
Write Javadoc to be read as source code
-
Making Javadoc readable as source code
-
Public and protected
-
All public and protected methods should be fully defined with Javadoc
-
Package and private methods do not have to be, but may
-
benefit from it.
-
think of it as internal design documentation when you revisit this code 8 months from now: - based on nothing but your well-chosen ;) package/class/method/variable names, will you recall all of your current design intentions and rationale? likely not - when you hand-off this code to another software engineer, how easy will it be to mostly rtfm? will you have to waste time preparing design/implementation notes specifically for the hand-off? if this is the case because the code is unreadable and not self-guiding and there's not already at least high level design notes in a wiki, you're doing it wrong!
-
-
If a method is overridden in a subclass, Javadoc should only be present if it says something distinct to the original definition of the method
-
ie. don't just copy-paste the javadoc from the superclass. that's mindless and pointless monkey work
-
-
Use the standard style for the Javadoc comment
-
Do not use '**/' at the end of the Javadoc
-
Use simple HTML tags, not valid XHTML
-
XHTML adds many extra tags that make the Javadoc harder to read as source code
-
Use a single <p> tag between paragraphs
-
Place a single <p> tag on the blank line between paragraphs:
-
this at least makes the paragraph breaks wysiwygísh and somewhat easier to read
-
-
Use a single <li> tag for items in a list
-
place a single <li> tag at the start of the line and no closing tag
-
Define a punchy first sentence
-
it has the responsibility of summing up the method or class to readers scanning the class or package
-
the first sentence should be
-
clear and punchy, and generally short
-
use the third person form at the start
-
Avoid the second person form, such as "Get the foo"
-
Use "this" to refer to an instance of the class
-
When referring to an instance of the class being documented, use "this" to reference it.
-
Aim for short single line sentences
-
Wherever possible, make Javadoc sentences fit on a single line
-
favouring between 80 and 120 characters
-
Use @link and @code wisely
-
@link feature creates a visible hyperlink in generated Javadoc to the target
-
@code feature provides a section of fixed-width font, ideal for references to methods and class names
-
Only use @link on the first reference to a specific class or method
-
Use @code for subsequent references.
-
This avoids excessive hyperlinks cluttering up the Javadoc
-
Never use @link in the first sentence
-
Always use @code in the first sentence if necessary
-
Adding a hyperlink in that first sentence makes the higher level documentation more confusing
-
Do not use @code for null, true or false
-
Adding @code for every occurrence is a burden to both the reader and writer of the Javadoc and adds no real value.
-
Use @param, @return and @throws
-
@param entries should be specified in the same order as the parameters
-
@return should be after the @param entries
-
followed by @throws.
-
Use @param for generics
-
correct approach is an @param tag with the parameter name of <T> where T is the type parameter name.
-
Use one blank line before @param
-
This aids readability in source code.
-
Treat @param and @return as a phrase
-
They should start with a lower case letter, typically using the word "the". They should not end with a dot. This aids readability in source code and when generated.
-
treated as phrases rather than complete sentences
-
Treat @throws as an if clause
-
phrase describing the condition
-
Define null-handling for all parameters and return types
-
ideally, if the method in question has any specified/required pre and/or post conditions, they should be noted in the javadoc, not *just* null handling also, there are cleaner ways to design around this type of old school null handling hackage
-
-
methods should define their null-tolerance in the @param or @return
-
standard forms expressing this
-
"not null"
-
"may be null"
-
"null treated as xxx"
-
-
"null returns xxx"
-
-
In general the behaviour of the passed in null should be defined
-
Specifications require implementation notes
-
Avoid @author
-
source control system is in a much better position to record authors
-
This wastes everyone's time and decreases the overall value of the documentation. When you have nothing useful to say, say nothing!
-
likewise with javadoc on things like default constructors /** * Creates an instance of SomeClass */ public SomeClass() {} is equally useless and unnecessarily clutters up the source code
-
