I have to admit something and it's a bit weird for a programmer to say, but I like comments. And I like them a lot, really a lot. If I'm really honest, I like them even more than code. So, now that I've said that, I really do feel relieved.
But seriously, as a freelance software developer I constantly 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 interesting conversations they all point out that comments only should be added when code cannot be self explanatory or really complex logic is implemented. They point me to books that I must read and how they've opened there eyes.
Don't forget that the code is meant to be interpreted by a computer.
I totally agree that using descriptive variable and function names, structure code in logical blocks/functions is a good 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.
But 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 really intrigued by their opinions and I lack the ability to convince them to look at my code differently. The outcome is always a respectful: "we agree to disagree". So therefor this article, to write down my opinions why I do like, no love comments.
Code in it's 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 is meant for human beings. Code on the other hand has a very limited 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 magic things out of their own. Therefor, my opinion is that code in it's essence should be the translation of your comments to a computer, and not the other way around.
When I want to learn something, what really 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 load and writing the translations down on paper. To my believe this can also be related to implementing requested functionality. Writing code and then providing comments on what it should do, gives me some kind of 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 have no effect on what is meant by it. This cannot be said about writing code. First of, the integrated development environment (IDE) really 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 literally not a waste of time.
Besides of the contents, comments also give structure to source code. Without it, code looks kind of 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 originally created the foundation of the old solution are not available anymore. At that moment it would be very helpful if there are comments 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 very happy 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 being 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 built on code that was written by me, they still joke about almost every line is accompanied with 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 complement I can get!