A very compact cheat sheet for the top Javadoc guidelines.

1. Javadoc guidelines
Miquel Martin – contact@miquelmartin.org

2. What’s this?
This slide set collects is meant to be a super compact
cheat sheet on Javadoc best practices, and I will
probably expand on it over time.
Photo credits:
The splashing coffee cup at the title by 96dpi on flicker: http://www.flickr.com/photos/96dpi/
2
Coffee beans on the watermark by wiedmaier on flicker: http://www.flickr.com/photos/wiedmaier/

3. Writing Javadoc
/**
* Returns the book titles by the author in this library.
* @parameter author the case insensitive author’s surname
* @return a sorted list of book titles
* @throws UnknownAuthor if the author was not registered in this library
*/
public SortedSet<String> getBookTitles(String author) throws UnknownAuthor {…}
General  Refer to collections as plurals (the authors as opposed to the Set of Authors)
 Refer to parameters as “the” and without details: “the author” and not “an author’s surname”
 Refer to the instance as this: “in this library”
 Keywords (true, false, null), special constants and file names must be written between as <code>true</code>
First Line  Start with a verb: “Send the something”, “Update the something” as opposed to “This method...”
 In classes, Do not start with “This class…”, “Instances of this class…” etc. Go straight into it: “Manager for all active
subscriptions in the system”
 End with a period. This will be the method summary.
 Add details in the same paragraph, or in a new one.
Parameters  Explain the parameter: “the case insensitive author’s name”
 By “default” parameters won’t be changed and null is not accepted. If that’s not the case, explicitly say so
 The parameter is assumed to not change. If it does, say so explicitly
 Don’t end in a period
Return  Explain what is returned not in what form: “the sorted list of book titles” as opposed to “a SortedSet of unique book
titles”
 Your method is assumed to never return null. If you do, say so explicitly.
Throws  Start with “if”
 Write in the past tense, e.g. “if a system exception occurred”
 Declare your unchecked exceptions 3

4. Extending and implementing Javadoc
 If you are implementing an interface or extending a class you can get away
with @inheritDoc
/**
* {@inheritDoc}
*/
@Override
public SortedSet<String> getBookTitles(String author){…}
 If there’s something to say in addition for this particular implementation,
add it. @inheritDoc will be replaced with the interface’s definitions.
/**
* {@inheritDoc}
* This implementation does not support catalogs from foreign libraries
*
*/
@Override
public SortedSet<String> getBookTitles(String author){…}
4

5. Thanks and Happy Coding!
5