Javadoc guidelines
3 likes2,143 views
This document provides guidelines for writing Javadoc comments, including starting the first line with a verb, explaining parameters and what is returned, mentioning exceptions thrown, and using @inheritDoc when implementing interfaces or extending classes. General guidelines include referring to collections as plurals, parameters as "the", and instances as "this", and writing keywords between <code></code>.
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