Javadoc guidelinesMiquel Martin – contact@miquelmartin.org
What’s this?     This slide set collects is meant to be a super compact     cheat sheet on Javadoc best practices, and I w...
Writing Javadoc/** * Returns the book titles by the author in this library. * @parameter author the case insensitive autho...
Extending and implementing Javadoc If you are implementing an interface or extending a class you can get away  with @inhe...
Thanks and Happy Coding!                           5
Upcoming SlideShare
Loading in …5
×

Javadoc guidelines

2,246 views

Published on

A very compact cheat sheet for the top Javadoc guidelines.

Published in: Education, Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,246
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
24
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

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

×