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.

Java Docs and Best Practices

669 views

Published on

This is the slide set I've used for JavaDocs and Best Practices session, which I did for the Carbon Team.

Published in: Software
  • Be the first to comment

Java Docs and Best Practices

  1. 1. Aruna Karunarathna JavaDocs & Best Practices
  2. 2. Adding Documentation to your code? ● Block Comments The compiler ignores everything from /* to */. ● Line Comments // text The compiler ignores everything from // to the end of the line. ● JavaDoc Comments /** documentation */ This indicates a documentation comment. (Doc Comments for shorter version...)
  3. 3. Demo
  4. 4. JavaDoc Important Tags ● @param ● @return ● @throws ● @deprecated ● @see ● @since ● @code ● @link
  5. 5. Adding Documentation to your code cntd.. ● What is this supposed to do? Answered only by the javadoc and method signature ● How does it try to do it? Answered only by the implementation ● Keep in mind the 80/20 rule. When designing API’s ● Refer the JDK code for further reference.. :)
  6. 6. JavaDoc Guidelines.. ● Write Javadoc to be read as source code ● Use @param same order as the parameters ● Keep a blank line between the Javadoc text and the @param or @return ● Public and protected ● Use simple HTML tags, too much HTML not encouraged..!!!
  7. 7. JavaDoc Guidelines Cntd.. ● Utilize the first sentence as much as possible. * This means the first sentence of each member, class, interface or package description * A concise but complete description of the API item. ● Use @code and @link wisely * Java keywords, package names, class names, method names,interface names field names, argument names, code examples * Keep in mind that audience is a advanced programmers use @link economically
  8. 8. JavaDoc Guidelines Cntd... ● Use lists for explaining set of options, choices ● Avoid second person for sentences and use the third person ● Document accepting or returning null ● Use "this" instead of "the" when referring to an object created from the current class. ● Use a single <p> tag between paragraphs, Don’t write too lengthy sentences
  9. 9. JavaDoc Guidelines Cntd... ● @param / @return guidelines @param x the x-coordinate, measured in pixels (Phrase Only) @param x the x-coordinate. Measured in pixels. (Phrase followed by sentence) @param x Specifies the x-coordinate, measured in pixels. (Sentence Only) @param x Specifies the x-coordinate. Measured in pixels. (Multiple Sentences)
  10. 10. JavaDoc Guidelines Cntd... ● Add description beyond the API name. /** * Sets the tool tip text. * * @param text the text of the tool tip */ public void setToolTipText(String text) {... } /** * Registers the text to display in a tool tip. The text * displays when the cursor lingers over the component. * * @param text the string to display. If the text is null, * the tool tip is turned off for this component. */ public void setToolTipText(String text) {...}
  11. 11. JavaDoc Guidelines Cntd... /** * Gets personal info. * * @param userId user id * @return Personal info dto. */ public PersonalInfoDTO getPersonalInfoDTO(int userId) { ... } /** * Gets a dto of personal info by querying the current list of users from * active directory * * @param userId The id of the user. Must be greater than 0. The ID is stored * in the application context or can be retrieved by a call to getUserIdByName. * @return A dto containing personal info. Returns null if the specified user * information was not found. */ public PersonalInfoDTO getPersonalInfoDTO(int userId) { ... }
  12. 12. References ● http://www.oracle.com/technetwork/java/javase/documentation/index- 137868.html ● https://github.com/ThreeTen/threeten/blob/0b071a60997f409e44b9bbccde013b 004f24fe22/src/main/java/javax/time/LocalDate.java ● http://blog.joda.org/2012/11/javadoc-coding-standards.html

×