Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Javadoc guidelines

2,543 views

Published on

A very compact cheat sheet for the top Javadoc guidelines.

Published in: Education, Technology
  • Be the first to comment

Javadoc guidelines

  1. 1. Javadoc guidelinesMiquel Martin – contact@miquelmartin.org
  2. 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/ 2Coffee beans on the watermark by wiedmaier on flicker: http://www.flickr.com/photos/wiedmaier/
  3. 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 periodReturn  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. 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. 5. Thanks and Happy Coding! 5

×