Keep Your Comments To Yourself

I’ve been writing code for well over 30 years now.

In 30 years of coding, I learned my code has to make sense to me long after I’ve written it. Later on, I started working on code shared with others. My code had to make sense to them, too.

When code got really complicated, I used to add a comment to explain it. I thought that would solve the problem. It didn’t.

Comments rot. We update the code, and forget to update the comments. Sometimes, the change happens far from the comment but still affects its correctness.

Quite often, comments imply our code would not be clear without them. This, in turn, means when I try to understand the code where it is used I am likely to have to navigate to its definition to read the comment.

Other comments are just the result of habit and add no value. Worse, some comments just add to the confusion.

I have learned to avoid comments almost entirely. It took me years to understand what self-documenting code meant, but I get it now.

Be explicit. Name your constants, variables, functions and classes based on what they do. Make sure the name is accurate. Avoid abbreviations.

If a line isn’t clear – refractor it. Extract a meaningful variable. Extract a well-named function. Move it to a well-named class.

With this insight, looking at my earlier attempts at clear code… Well, I have no comment.

(You can read about this idea in depth in Uncle Bob’s Clean Code)

I may get commissions for purchases made through links in this post.

Published by eranboudjnah

A software consultant and tech lead. Passionate about optimizing as many aspects of my life as possible, to free time for what really matters.

2 thoughts on “Keep Your Comments To Yourself

  1. No here I completely disagree with you. All code should be commented. Comment your code at the top of the file with what is contained in the file. Code comments should read like a story so that the reader does not have to decode what you are doing. It’s not always obvious just by reading some clever code you wrote what you were thinking at the time, even if at the time it was obvious. The number of times my extensive comments have saved me has far outweighed the cost of writing them. I have even had work colleagues who had to pick up my code later thank me for the comments which saved them hours of reverse engineering and rewriting.


    1. This is a terribly outdated approach to writing code.

      If your class is named well, you don’t need a story to tell you what it does. That’s why we abstract. How it does it is an internal detail. If that detail is written well, it requires no comments either.

      Comments grow stale. At some point, not only do they become inaccurate, but they can become entirely misleading. So it’s not about the cost of writing comments, it’s about the inevitablity of them growing stale.

      If you are trying to do something clever in your code, you may be over-engineering. Write simple code, optimise when necessary. When that happens, use clear naming to express the idea.

      Lastly, document with tests. A clear test is a live document that validates your code.

      To make sure your code is clear, get your code reviewed. Pair program.

      Challenge yourself to write clear code without comments. Your code would be much better than an enigma with a comment.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: