1. Home
2. The Art of Code Commenting: Best Practices and Common Mistakes

The Art of Code Commenting: Best Practices and Common Mistakes

Code commenting might seem straightforward, but it’s more than just a few lines of text that describe what a code block does. Commenting is the practice of writing clear and concise textual context around code to help others understand what it does or why it was written. Effective commenting can help make a project more approachable, especially when other developers need to work on the codebase.

On the other hand, poorly written or absent comments can lead to confusion, frustration, and decreased productivity. It makes code difficult to maintain and may drive others to outright reject collaboration on a project.

In this post, we’ll go over some best practices and common mistakes related to code commenting. Follow these practices to improve code maintainability, reduce errors, and help other developers approach the project with greater ease.

Best Practices

Use concise and clear language

Using clear and concise language will help others quickly understand your comments. Avoid using verbose, flowery language that obscures your meaning. Use simple words, sentences, and a straightforward writing style. Remove any unnecessary words, and carefully consider the phrasing to make sure it accurately conveys your intended message.

Comment high-level and complex functionality

One of the most common purposes of comments is to describe high-level functionality. This might involve a block of code that has several different responsibilities, or code that is particularly complex. Commenting these sections can provide others with a map of how the code works, and in some cases, highlight any edge cases or troubleshooting areas.

Comment your intentions

It is crucial to comment why you’ve written a block of code. This is particularly important when working on a large project or codebase. Developers who join the project later on might not be familiar with the project’s history, so it's best to assume the reader knows next to nothing. Detailed comments will also help you see mistakes the first time around.

Comment edge cases and gotchas

Even if edge cases only occur under unique conditions, they can still cause problems down the line. Your code should aim to handle edge cases, describe the gotchas in detail in comments, and should document how those conditions are handled.

Use inline commenting

Inline commenting is commenting on the same line as the code you are describing. Use inline commenting to describe why you have written a block of code and to describe how that code is working. Too many inline comments can cloud the code and needlessly complicate it.

Common Mistakes

Over-commenting

While commenting is necessary, too much is not always a good thing. Over-commenting can lead to less readability, your code not being properly understandable, and can be counter-productive. Stick to the best practices we’ve recommended and use comments sparingly.

Outdated comments

If you’re using an older codebase, it's possible that a comment may no longer be valid. This comes down to a failure to update comments alongside code changes. This creates a discrepancy between the expected behavior of the code and the actual process it follows. Solutions range from adding a comment that states the code hasn’t been tested since a certain change or immediately updating with the new behavior.

Inconsistent commenting patterns

Inconsistent commenting patterns can confuse other developers who may be required to work on the code in the future. An example of inconsistent commenting patterns is when you may write inline comments for one of your functions and not for others.

Too many short comments

Too many short comments, especially when they are simple and straight forward, have the potential to burden your code. Where possible, you should consolidate or eliminate consecutive in-line comments. If such a comment is necessary, ensure it is worthwhile and adds value and context to the code.

Conclusion

Commenting is an important aspect of writing maintainable code. It's necessary to keep other developers informed about the code’s intention, edge cases, and any potential problems that may need to be addressed in the future. The best code commenting is clear, concise, and aligns with industry best practices.

Make sure to follow our recommended best practices when commenting to create documented software that's easier to maintain and read. Avoid common mistakes that can detract from the readability and reduce the quality of the comments in your code. With these insights, you can better master the art of code commenting.