Skip to content

Thoughts about code comments

3 min read

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.

Write comments first.

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.

Avoid comments for comments sake

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 a 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; 

Remove any code that is commented out

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.

Comments should not repeat documentation

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.


Related Posts

Document your work!

Reasons why documenting work can help you be more effective in the long term.