...
- 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 (non-null, not empty, value range, etc.) for every input parameter.
- Short description and constraints (non-null, not empty, value range, etc.) for the returned value if any.
- Short description for exceptions and under what condition they will be thrown.
- NoteNotes:
- 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.
...