Following are 13 tips on how to comment your source code so that it is easier to understand and maintain over time.
1. Comment each level
Comment each code block, using a uniform approach for each level. For example:
- For each class, include a brief description, author and date of last modification
- For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.
2. Use paragraph comments
Break code blocks into multiple “paragraphs” that each perform a single task, then add a comment at the beginning of each block to instruct the reader on what is about to happen.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .3. Align comments in consecutive lines
For multiple lines of code with trailing comments, align the comments so they will be easy to read.
const MAX_ITEMS = 10; //maximum number of packetsconst MASK = 0x1F; // mask bit TCP
Some developers use tabs to align comments, while others use spaces. Because tab stops can vary among editors and IDEs, the best approach is to use spaces.
4. Don’t insult the reader’s intelligence
Avoid obvious comments such as:
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
This wastes your time writing needless comments and distracts the reader with details that can be easily deduced from the code.
5. Be polite
Avoid rude comments like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.
6. Get to the point
Don’t write more in comments than is needed to convey the idea. Avoid ASCII art, jokes, poetry and hyperverbosity. In short, keep the comments simple and direct.
7. Use a consistent style
Some people believe that comments should be written so that non-programmers can understand them. Others believe that comments should be directed at developers only. In any event, as stated in Successful Strategies for Commenting Code, what matters is that comments are consistent and always targeted to the same audience. Personally, I doubt many non-developers will be reading code, so comments should target other developers.
8. Use special tags for internal use
When working on code as a team, adopt a consistent set of tags to communicate among programmers. For example, many teams use a “TODO:” tag to indicate a section of code that requires additional work:
