Why I love comments!

But seriously, as a freelance software developer, I continuously meet new people, programmers, and most of them have to point out after having done a few peer reviews, during lunch breaks, that I write a lot of "unnecessary" comments. And during those exciting conversations, they all point out that comments only should be added when code cannot be self-explanatory or complex logic is implemented. They point me to books that I must read and how they've opened their eyes.

Don't forget that the code is meant to be interpreted by a computer.

I agree that using descriptive variable and function names, structure code in logical blocks/functions is an excellent way to improve readability and make code more understandable for human beings. There is nothing wrong with that; however, don't forget that the code is meant to be interpreted by a computer.

Why do colleagues think that most of my comments are obsolete and don't add any value to the application we are building together? I'm intrigued by their opinions, and I cannot convince them to look at my code differently. The outcome is always respectful: "we agree to disagree." So, therefore, this article, to write down my opinions why I do like, no love comments.

Code in its essence should be the translation of your comments to a computer.

The difference between comments and code is that comments are written in a natural language, such as English, and are meant for human beings. Code, on the other hand, has a minimal vocabulary and provides instructions to a machine, a thing that is evenly smart as water, my toilet seat, or dumbbells I train with. Don't know about your experience, but these don't do magical things out of their own. Therefore, my opinion is that code, in its essence, should be the translation of your comments to a computer and not the other way around.

When I want to learn something, what helps me is to look at the subject from different perspectives. Like learning words in a new language, I know that I can give my memory a boost when I combine saying them out loud and writing the translations down on paper. To the best of my belief, this can also be related to implementing the requested functionality. Writing code and then providing comments on what it should do, gives me some self-correctness. It often happens that when I add a comment, my mind says: "nope, that is not completely what the code instructs the computer to do.".

Adding comments is literally not a waste of time.

Another point to note is that when typing comments, I can easily get 300+ characters a minute. Usually, small typo's in comments do not affect what is meant by it. This cannot be said about writing code. First, the integrated development environment (IDE) has to help me to autocomplete code to improve typing speed and point me at every little syntax error; otherwise, "the computer says no!". So, adding comments is not a waste of time.

Besides the contents, comments also give structure to source code. Without it, code looks naked to me. The structure it provides helps me in the same way as formatting and syntax highlighting. You can easily spot where functions start and end (because doc-blocks) and see at a glance where the more complex pieces are in a function.

Comments don't age as fast as code does.

Professionally, I have encountered many projects where code is/was created to be disposable; the idea is/was that it should only last until the next version. However, in reality, updates and extensions were made during the years until the environment/ programming language (version)/framework the application was build on/with has become severely outdated (i.e., security support has been dropped). At that moment, the same functionality with extension has to be created using new techniques, and the developers that formed the foundation of the old solution are not available anymore. At that moment, it would be beneficial if comments are explaining why something was implemented that way, what it does, or better yet what it should do, and not only for the 10% that the original programmer thought was complex.
Hopefully, when the focus shifts from disposable to more durable solutions, requiring more comments is not forgotten. Comments don't age as fast as code does.

For me, comments are more than the tool you use to temporarily prevent running pieces of code during development or only be allowed to explain the most complex parts of an application. I'm delighted that frameworks like Drupal provide extensive comments (they even enforce them in their coding standards). Otherwise, I don't think I could have found my way around in all the great features Drupal provides.

And since I'm honest about it, and although it frustrates me when I have to use code that lacks comments, a part of me is also fine with this. Eventually, I always do understand code that has to be refactored, extended, or re-implemented, and the longer it takes simply means the more I get paid. It's that simple. So now and then, when I speak to former colleagues that have to build on code that was written by me, they still joke about almost every line is accompanied by comments and how easily they can spot the parts I created. But in the end, they have to agree that everything is understandable from the start, and that's one of the biggest compliments I can get!