Thoughts about code comments
Argues for comments that explain code's purpose to other developers, serving as a guide and documentation extension rather than code repetition. It also stresses deleting commented-out code and relying on source control.
Table of Contents
For many years, I thought my code should be clean and easy to read, and therefore I don’t need to use comments. The code itself should be “self-documenting”.
Over time, my view on comments has changed. I’ve learned to appreciate comments in my solutions, especially when I’m not the only developer.
I’m currently reading A Philosophy of Software Design, which has a section of the book dedicated to comments in your code. The author’s viewpoints aligned with my own.
I find it easier to write the comments for a new piece of code before writing the code. The comments would describe what the code needs to do. It’s purpose.
This acts as a guide while writing the code itself. It sets boundaries. If the code starts doing more than it was originally intended, perhaps it should be refactored.
If you don’t know what the comments should be until after you write your code, then perhaps you need to take a step back and understand what you’re about to do before you attempt it.
Of course, your comments would be updated as you write the code to fill in the blanks and ensure accuracy. The “how” of writing code is often different from the “what”.
It’s helpful to go back and revise the comments during, and after, the code has been written.
Developers should not have to read the code to understand its purpose
As I briefly mentioned in the introduction, I had the mindset that the code should be “self documenting”. A new developer can open the code and read through line-by-line and understand what it does.
While I agree the code should be clean and readable in that way, why not tell the developer in the comments what to expect instead of making them read through all the code directly? What if they don’t need to introduce changes to the code? They only need to know what it does so they can use it along with their code?
In retrospect, it seems cruel to make a future developer read, line-by-line, to figure out what the code is supposed to do when it can be summarized in a one paragraph comment.
In this example, the comments are completely overkill. I used to write comments like this all the time. It thought I was being a “good developer”. But in reality, I was adding a lot of extra text that was completely unnecessary.
// Take input of a and add it to the input of b and return the result
// Parameters:
// a: The first number to be added.
// b: The second number to be added.
static int AddNumbers(int a, int b)
{
return a + b; // returns the sum of a \+ b*
}
Instead, describe the purpose in short, concise words. This function is so simple, it does not need additional comments to understand what it does.
// Takes two input parameters and returns their sum.
static int AddNumbers(int a, int b)
{
return a + b;
}
It drives me crazy when I look at some code and see 40 lines of code commented out because it is no longer being used. If we no longer require it, delete it!
I was guilty of this in the past. I didn’t want to lose previously written code, “just in case” we needed to refer to it. Or I wanted to keep a running history of changes.
This is what source control is for! You can safely delete it and still refer to it later. Your source control commits should explain the change history.
There is a difference between comments and documentation. I believe comments should be close to the code with the purpose of helping the developer who is writing the code and also any future developers who are reading the code. It is a guide to what can be expected in the code that follows.
Documentation, on the other hand, describes the system at a higher level. Its audience consists of other roles, like architects, product managers, etc.
The comments in your code can link to related documentation, rather than repeating it.
The comments in your code should be an extension of your documentation, not a copy or replacement of it.
The Weekly Cache
A weekly newsletter where I share what I did, what I learned, what I discovered, what I read, and more. Each edition is short and to the point, and packed with interesting links.