Tip of the Day: Documentation Code Review

Documentation

Here are some general best practices to consider around documentation code review.

These tips are by no means definitive, but serve as reminders to developers what they should consider in a checklist.

Note: documentation and code reviews are really not separate processes.

• All methods are commented in clear language. If it is unclear to the reader, it is unclear to the user.
• All source code contains @author for all authors.
• @version should be included as required.
• All class, variable, and method modifiers should be examined for correctness.
• Describe behavior for known input corner-cases.
• Complex algorithms should be explained with references. For example,  document the reference that identifies the equation, formula, or pattern. In all cases, examine the algorithm and determine if it can be simplified.
• Code that depends on non-obvious behavior in external frameworks is documented with reference to external documentation. 
• Confirm that the code does not depend on a bug in an external framework which may be fixed later, and result in an error condition. If you find a bug in an external library, open an issue, and document it in the code as necessary.
• Units of measurement are documented for numeric values.
• Incomplete code is marked with //TODO or //FIXME markers.
• All public and private APIs are examined for updates.