JavaDoc Rules

For the sake of readability and structure we agreed in the “Community of Practice” on consistent rules for our API description: We should document our entire API mandatorily and the internal classes optionally when we consider them important. API classes are inside a package api, internal classes inside internal.

Currently we don’t have a styling rule for method parameter references. We will discuss this in the future, when we’ve tidied up our JavaDoc

Class Description
1. The first sentence should start with the name of the class.
2. The first sentence should be a summary sentence, containing a concise description of the API item. It should rather describe the role of the class than its certain behavior.
  Example: (TaskService)
  1. “The TaskService creates, deletes and transfers Tasks.”
  2. “The TaskService manages all operations on Tasks.”
Enum Description
1. The first sentence should be a summary sentence starting with the name of the class.
Method Description
1. The first sentence should describe the intended purpose of the method precisely.
  1. starts with verb in 3. Person (uppercase)
  2. ends with dot
  3. afterwards new paragraph
    Example:
  /** * Transfers the specified Task to another Workbasket. <p>
2. The inner logic of the method should be described so far that the user knows, which side effects are involved when calling a method. It should describe how the states of the objects are affected by the method. It should not describe every internal detail about the way the method proceeds.
  Example:
  /** * {@linkplain Task#isTransferred() isTransferred} is set and {@linkplain Task#isRead() isRead} is reset. The {@linkplain Task#getState() state} is set * to {@linkplain TaskState#READY} and the {@linkplain Task#getOwner() owner} to NULL.
3. Getter should be described using “Returns …” instead of “Gets …”.
  Example:
  /** * Returns the id of the parent Classification. * * @return parentId */
4. Getter that have return value of type boolean should be described using following phrasing:
  i. Returns true if ... or
  ii. Returns whether …
Parameter Description (@param)
1. Used for every Parameter passed to a method.
  Example:
  1. only a phrase
  2. begins with “the” (lowercase) or with a verb
    1. The noun followed by “the” should not reference the parameter name.
  3. ends without dot
  4. when more information / phrases necessary, divided by a semicolon
2. If not setter method: Should add description beyond the API name of the parameter.
  Example: (workbasketKey)
  1. “the key of the Workbasket”
  2. “the key of the Workbasket the Task should be transferred to”
Return Value Description (@return)
1. Used for every non-void method.
  Example:
  1. only a phrase
  2. begins with “the” / “a” (lowercase)
  3. ends without dot
  4. when more information / phrases necessary, divided by a semicolon
  5. proposal: the return value of a getter consists only of the parameter name, without “the” or “a” in the beginning
Exception Description (@throws)
1. Used for every Exception thrown by a method.
  1. only a phrase
  2. begins with if (lowercase)
  3. ends without dot
  4. when more information / phrases necessary, divided by a semicolon
2. Should add description beyond the Exception name.
  Example: (NotAuthorizedException)
  1. “if the user is not authorized”
  2. “if the user has no transfer permission for the source Workbasket”
Overloaded & setter Methods (@see)
1. Used for overloaded methods when…
  1. …they are chained
    Example:
  2. …the logic of both is identical
    Example:
    transfer by Key and Domain vs. transfer by Id
2. Used also for setter-methods and referring to the corresponding getter-method.
3. Explain the method in one phrase as done with all other methods, but leave out further information. Just refer with @see to the called / almost identical method which should describe all necessary information as specified. If the parameters differ, only explain the different ones.
4. Use the annotation @SuppressWarnings("checkstyle:JavadocMethod") to circumvent Checkstyle.
  Example:
Linking Classes (@linkplain)
1. We should link…
  1. …all our mentioned public API TASKANA classes.
  2. …fields by their corresponding getter-method.
  3. …public methods (without additional text).
  Example:
2. We should only link components of our public API. We should not link…
  1. ...internal classes, e. g. TaskImpl
  2. ...classes from external libraries, e. g. List, Map or Instant
  3. ...the class or its attributes itself, e. g. not link the id of the Task in Task
3. When linking a class while referring to multiple Instances we include the s within the link.
  Example:
Linking (Entity) Attributes
1. When referencing an attribute of a class, we link it to it’s getter-method. The display text of the linked value should match our Entity naming guide, found in Backend Coding Guidelines.
  Example:
Linking Enum values
1. When referencing an enum value, we link to the value only. No text should be added to the link.
  Example:
Spelling and phrasing
1. When referencing attributes from their class, use either the description of their content, or their original names.
  Example:
2. 'NULL' is written in uppercase
3. 'id' is written in lowercase, except in the beginning of the sentence
4. Instant, Map, List and other external classes and data structures are capitalized
5. Everything else starts with lowercase or uppercase according to English grammar
6. Use contractions like wasn’t, isn’t and doesn’t (instead of the full versions)