Commenting code is a point of contention between programmers in almost every work group. Many programmers think that it's unnecessary. The slightly less hard-core claim that time spent writing comments is wasted because it could have been spent writing code.
I know many, many people on the Internet have weighed in on this argument. It's worse than Tabs vs. Spaces. I doubt I can say much that hasn't been said before, but I'm frustrated, and hoping that I can put together a clearer and more convincing argument than those before me (admittedly a faint hope).
I'm a believer in comments. I acknowledge that part of this is because I have multiple projects spread across multiple languages (Ansible, Bash, Groovy, Java, Python, VimScript) and many years, so I often come back to them later and wonder what I thought I was doing. This has been motivation enough. But many people seem to genuinely believe that "I don't need to comment my code because the code documents itself." There are a number of blind assumptions that accompany that thinking:
- the language is totally clear and unambiguous
- human language is staggeringly ambiguous. Programming languages are better, but even they haven't achieved perfect clarity yet.
- the language is static and never changes
- for the first three years my company used Ansible (2015-2018), the language changed every four months: we had to rewrite constantly, and a description of what was to be achieved definitely helped. Even C and Cobol continue to change (slowly), so code can break. Hell, if you change platforms, the concept of "Integer" changes!
- you wrote perfect code
- Donald Knuth writes perfect code. You don't.
- your perfect code works (ie. there are no bugs in the language, now or ever)
- code may be "perfect" now, but it can be broken by intentional changes in the language (mentioned above) and also by unintentional changes (aka "bugs") being introduced to the language
- your successor and/or co-workers think as you do, and prefer the same programming models
- even if you write perfect code, you're assuming that those that touch the code after you are as clever as you and can understand the difficult parts. You're also assuming these people use the same short forms and behaviours that you like. Perl has 5-10 ways to do almost anything, and not only are many of these alternate methods opaque, but most programmers only know a couple of those methods because they can get the job done with what they know.
- nothing in your associated infrastructure has required any exceptions
- it's inevitable that the code you write has exceptions for strange behaviours or set-up in your infrastructure or other local code. You didn't use the "obvious way" because you tried that and it doesn't work, and if you don't document that the next coder will spend hours "fixing" your code only to find this out (and possibly causing a catastrophic failure).
Another reason I've heard for not commenting code is that "comments get out of date." Seriously? So does THE CODE. That's why you're updating it! If you're in a comments mindset (which I hope the above has convinced you you should be), you'll update the comments with the code.
It all comes down to two things: maintenance, and it's not about you. When has code ever not needed maintenance? Again, you didn't write perfect code: a bug will be found and need to be fixed. And it will be fixed a lot faster if the comments help the next coder to understand what's happening. Even if you wrote perfect code, people will want to add features. And again, that means someone reaching into your code and needing to know how it works. Even when it's you, how well do you remember the code you wrote six months ago? How about two years ago? In a work environment, this can become an adventure in institutional memory and Code Folklore: does anyone remember why this block of code exists? How many years does your institutional memory cover?
Your comments are a lifeline to the coders that follow after. Think about maintaining the code yourself, and do that future coder a favour: explain what the hell is going on.