Code Comment Guidelines

Owned by Brendan Hofmann
Last updated: Nov 03, 2016 by Eric Lessard (Deactivated)
3 min read

Java

  • All externally-facing classes, interfaces, annotations and exceptions should have proper JavaDoc comments.
    • Interfaces should describe the contract between their clients and their implementers and how they should be used.
    • Classes should describe the contract between them and their clients, how they should be used and, if needed, why they behave the way they do or should be used the way they are. They should not however provide any implementation details as those are not part of the contract and implementation changes should have no effect on the class' clients.
    • Annotations should describe their purpose, where they should be used and what effect they will have on the code they annotate.
    • Exception classes should describe in what context they should be used, when they should be thrown and caught, and what information they convey.
  • All externally-facing public and protected methods should have proper JavaDoc comments and annotations. This includes:
    • Short description and constraints (not empty, value range, etc.) for every input parameter.
    • Short description and constraints (not empty, value range, etc.) for the returned value if any.
    • Short description for exceptions and under what condition they will be thrown.
    • Notes:
      • Setters and getters should have JavaDoc comments only if their input parameter or return value have special constraint.

      • By default, the assumption is that methods will not accept or return null. If that's not the case, the javax.annotation.Nullable (@Nullable) annotation should be used to indicate the fact that null is accepted and/or returned.

  • All externally-facing public and protected methods that are meant to be overridden should include information about how and when they should be and what the contract is between themselves and the calling method. This is especially true for abstract methods.
  • Package private (default visibility), private methods, or otherwise internal code do not have to include JavaDoc comments. If their purpose cannot be clearly conveyed by their name and the name of their parameters, use just as much javadoc as necessary to communicate the behavior.
  • When referencing a type in the JavaDoc comments that is not required as a compile time dependency, use the fully qualified name of the type instead of adding an import. E.g., if a comment wants to refer to Java's Date class but the code itself doesn't need it to compile, the comment should use {@link java.util.Date} instead of importing the Date class.

Javascript

  • Reuseable/library code should be documented in a readme.
  • Endpoints/interfaces/message structures (e.g. cometd and json) should be documented in source.

XML

  • Maven dependencies sometimes require exclusions or unusual versions. These should be explained.
  • WSDLs should clearly document their interfaces using the documentation tag.
  • XSDs should be documented using the annotation tag.

General

  • Inline comments should be avoided, with the following exceptions:
    • particularly complex pieces of code that necessitate step by step explanation
    • weird or bad looking code necessitated by third-party dependencies or other external constraints (reference ticket numbers and note when it can be removed where possible)
  • TODOs are only permissible for issues that cannot be immediately resolved due to third-party or external constraints. They should always reference a ticket number so we know when they can be fixed.
  • Commented out code should be avoided. Delete it or fix it.
  • If in doubt, show your code to someone who is unfamiliar with it. Can they understand what it is meant to do and how it works, at least at a high level? If not, it needs more comments or better naming conventions.

Examples