Sometimes I see devs say things like "good code doesn't need comments". The rationale being, if your code is well-written, it should be self-explanatory to the next developer that's looking at the code.

Actually I used to say that as well, but that was mostly because I was (and maybe still is?) quite a lazy commenter. I thought "how would I not understand my own code?" as long as it's written clearly enough? Don't even get me started on writing design documents or maintaining them, but I'll leave that for another topic.

But at some point I started to appreciate comments, so I'd like to share my thoughts on it by sharing some experiences I've had while writing code, which might offer some insight into why even the best code might benefit from having comments.

Story Time

I wrote an article previously about web scraping. If you're interested in scraping or having issues with getting scraped, might be something to read, but it's not related to this story besides that I write various random tools like scrapers and bots.

In particular, my tools come in different flavours

• some of them run on a server constantly listening to web hooks
• some of them wake up once every hour or so to poll for data
• some of them fire up a browser to navigate a couple pages
• some of them transform data from one format to another as part of a pipeline

Basically they all do different kinds of things. They're all tools that are written to solve specific problems, and most of these deal with completely different problem domains. Some of these scripts are about 10-20 lines long, others might be 100+.

I have dozens of these small tools lying around, some of them I've never looked at for years but still in use.

Why Did I Write That Again?

Websites will change. API's will change. Data formats will change.

Basically, requirements change. It's just how things are and you just have to deal with it when it happens. If you're lucky, things might not change that often, but on the flip-side, because it doesn't change that often, you don't look at your code that often either.

Eventually you'll start forgetting details, and one of the most frequent problems I've had when one my tools crashes is I have no idea why my code is doing what it's doing!

How Self-Explanatory is Good Code?

When I look at my code, I know exactly what it's doing, because I came up with descriptive variable, method, and class names. I have spaces after each comma, and good indentation or curly brace placement to make that code look clean and absolutely fabulous.

Indeed, it should be quite self-explanatory what the code is doing, but there are so many things that self-explanatory code fails to explain

• Is this code correct?
• Why is it written this way?
• How should this code be used?
• What problem is the code meant to solve?
• Are there better ways to solve the problem?

Of course, "what is this code doing?" is an important question as well, but that's just one out of many other important questions that I have when I look at a piece of code.

Beyond My Code

At some point, I started moving away from only reading and writing my own code. I started using libraries. I started using frameworks. I started code-reviewing. I started extending other developers' code.

Not only do I need to understand the problem, I also need to understand how you've attempted to solve the problem through your code. I might be able to understand what your code is doing, but then I might have to put it all together to understand why you wrote it that way.

Most of the time it's not like my 100-liner simple tools that do just one or two jobs, some of these could be massive 100000+ line codebases with hundreds of classes and components written by dozens of developers over the course of many years.

It really can take a lot of time to truly understand what the code is doing, and not having any comments to help explain the purpose of the code can make it that much harder to put things together before you can actually dig in and write something of your own!

We are Problem Solvers

The biggest lesson I've learned in software development is understanding my role as the coder. The code is simply a solution to someone's problem, and there's an entire process that you (or someone else) go through before you arrive at the final solution that will be turned into code and delivered.

By writing comments to explain the purpose of your code and a bit of the thought-process that goes into it, it will greatly benefit the next person (perhaps yourself even) who looks at your code and wonder why you wrote it and how it should be used.

Feedback?

What are your thoughts on comments to explain your code? Are there strategies to good code writing that can allow you to express your thought process without necessarily writing it as comments? I'd love to be able to read a piece of code and understand the big picture behind it since it minimizes the amount of text I'd have to write.