Consistent, comprehensive, and thoughtful documentation is vital for maintaining a readable and sustainable codebase. Adherence to these guidelines will ensure the documentation is as valuable as the code it explains.
Language
All documentation must be written in English. Use simple and clear sentences—documentation should communicate ideas effectively, not showcase complex language.
Purpose of Documentation
The principal aim of code documentation is to facilitate understanding for other programmers. Code comments should primarily explain why specific decisions were made, not what the code is doing. If the purpose of a piece of code is not obvious, make sure to document why it exists. Often, the why provides more valuable context than the how.
Avoid Documenting the Obvious
Refrain from writing comments about obvious code operations. Unnecessary comments can create clutter and must also be maintained, potentially leading to inaccuracies if not updated alongside the code they describe.
Write Self-Documenting Code
Strive to create self-explanatory code—this is the best form of documentation. If a comment can be eliminated by refactoring or renaming parts of the code to make their function more obvious, prioritize that approach.
This guideline should not be used as an excuse to avoid comments entirely. Despite the benefits of meaningful names and well-structured code, some constructs, such as DateTime formatters or Regular Expressions, may still be inherently obscure. In these cases, as well as when the purpose of the code is not immediately clear from its structure, comments are essential.
Examples
// Bad
int d; // The duration in days
// Better
int durationInDays;
// Bad
// Check if the employee is eligible for full benefits
if ( ( employee.flags & HOURLY_FLAG ) && employee.age > 65 )
// Better
if ( employee.isEligibleForFullBenefits() )
// Necessary
String regex = "(\\d{3}-\\d{2}-\\d{4})"; // US social security number (SSN) pattern
In all cases, strive to find the balance between well-written code and effective documentation, to create a codebase that is as self-explanatory as possible, but still well-documented where necessary.
