How to comment code meaningfully: a best practice guide
Code can only tell you how the program works; comments can tell you why it works. Try not to shortchange your fellow developers in either area.
– Jeff Atwood
The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. – Robert C. Martin
– Robert C. Martin
Commenting code is a divisive practice amongst developers. Where your code instructs a computer what to do, your code comments describe what you want a computer to do to other developers.
Code comments explain why the program is being written; the rationale behind this or that method; the reasons certain approaches were taken.
So, what’s so divisively problematic about that? Unfortunately, done poorly, code comments act as a hallmark to sloppy code. They harm without adding much value.
Done well, however, commenting code provides important or useful information and context that the code alone cannot express.
The question is, then, how to comment code meaningfully?
The foundation of code comments
Knowing how to comment code meaningfully starts with understanding what makes code comments useful.
Code comments are for clarifying the purposes and reasoning behind a function or component of the code. They can outline the parameters a function accepts, or summarise what a section of code does.
Sometimes, developers comment code that’s too complex to understand. However, this type of comment can be a sign of technical debt, and an indicator that the code should be cleaned up. So, this is an unpopular style of code comment.
When you comment code, you’re helping others (and your future self) understand the code. This is useful because sometimes, we need to go back over the code we’ve written in the past. Sometimes someone needs to maintain or update your code when you’ve moved to other projects.
Code comments also aid with mentoring. They can point to overly complex code. Or note where a bug has been found and fixed.
How to comment code meaningfully
Meaningful code comments, then, are those that add value and clarity. For instance, you should use code comments to:
- Explain unidiomatic code
If there’s a section of code that’s not standard or written ‘ungrammatically’ for a reason, use a code comment to explain why you’ve chosen to write it that way.
- Highlight bug fixes
You shouldn’t just add comments while writing the code initially — but also while you’re updating and modifying it. This is particularly true when it comes to bug fixing. Here, you can use a comment to provide the context of the bug you’ve fixed.
In turn, this can later be used to ensure the code is accurately and efficiently tested. Plus, it can help others decide further down the line if the fix or piece of code is still needed.
- Mark incomplete implementations
You should use TODO comments to highlight areas where you’re expecting something to be added later. This aids with technical debt management, and helps you find the areas in your code you may need to modify.
- Explain why you’re doing something
Many developers comment code to say what they’re doing — but they all too often forget to include why they’re doing it. The why behind your code is the context — it connects your code to the designing decisions behind it.
What not to do
Understanding how to comment code meaningfully also means knowing what not to do.
- Don’t be a jerk
Maybe you’re going through someone else’s code and you think it’s bad code. You find a section that, to your mind, needs to be rewritten. Don’t use a code comment to call the person out. Pointing out a mistake or overly criticising the code publicly with a comment doesn’t make you seem good at your job — it makes you seem uncooperative.
- Don’t over-comment (a.k.a. don’t duplicate code)
There’s no value in commenting code to explain every single line. This makes your code look messy, wastes time and effort, and doesn’t add any value. If anything, comments that add no information have a negative value.
Use comments only to summarise sections, clarify key areas, and add meaning to your code. Not to explain every line you’ve written. Good code, after all, will usually speak for itself.
- Don’t rely on comments to get away with complicated code paths
Yes, when you comment code, you provide information the code can’t. However, this can quickly become a safety net to fall back on any time your code gets too complex or a bit too messy.
Relying on code comments rather than taking the time to simplify your code (where possible) makes for code that’s too hard to understand and prone to errors.
In short, don’t use comments to excuse unclear code.
How to comment code
Some developers argue that comments are unnecessary, merely shining a light on unclear code. But meaningful code comments are a boon, not a hindrance.
By knowing how to comment code in a meaningful way, you remove the negative connotations around the practice of commenting code. You make way for a clearer code base that’s easier to work with as part of a team.
Or, in the words of Damian Conway: “Documentation is a love letter that you write to your future self.”
Useful links
The myth of the clean code base
