Annotations, documentation and comments

The sections below include the coding conventions with respect to annotations, documentation, and comments.

Annotations

  • Do not have spaces around the @ symbol.
  • Indent annotations to align them with the starting position of the owner (statement or definition).
  • Each annotation attribute (i.e., key-value pairs) can be expanded and block indented on its own line or kept as inline fields.

Example,

  • If an annotation is empty, place it in a single line and do not have spaces between both braces.

Example,

  • If you are annotating a parameter or a return type, the annotation should be added inline to the parameter or the return type.

Example,

Comments

  • Use // for both single-line and multi-line comments.

Example,

and

  • Add a single space between the // and the content.
  • If the comment is in its own line, then indent it considering its context (i.e., top-level or in a block).

Example,

  • If the comment is in line with the code, add a space before it.

Example,

Documentation

  • Always, indent them to align with the starting position of the owner.
  • Add a space after the # symbol.
  • Add an empty line after the description.

Example,

  • Add only one space after the parameter marker (+), divider (-), and return.
  • Begin the param identifier and description with a single space.

Example,

"Star"

"Watch"