One of the perennial debates in programming is about the value of commenting code. This wasn't even a debate when I learned the craft, but there seems to be a mostly-generational shift toward eschewing comments. There are lots of excuses, but I think it mostly comes down to one thing: commenting is an exercise in empathy. If you can understand how a future programmer might struggle to understand the code well enough to change it without inviting disaster, and have a desire to spare them that pain, you comment code. If you don't have that understanding or desire, you don't comment. Too many programmers don't have enough empathy to outweigh laziness (or sometimes ego). This is most clearly evident in the fact that most anti-commenters also reject alternatives such as external documentation, and are often among the first to demand that all code be updated to use every feature in the latest language standard before the ink even dries. They don't care about the consequences for maintainability or future-programmer sanity. They just want to grind out code, claim it as "impact" in their next performance review, and then abandon it as they try to climb the next rung of the career ladder. Here are some of the excuses they use.
- "Good code is self-documenting."
O RLY? If you're using a not-well-known algorithm or tweak to an algorithm, perhaps even one you developed yourself and which is thus known to literally nobody else, then it needs to be explained. Function and variable names are simply not an expressive enough medium in which to describe that. They might be sufficient to describe the current implementation of that algorithm so that it can be replicated e.g. in a different language, but they can't describe the tradeoffs that led to that algorithm being selected. They can't describe the subtle details that make it better than alternatives, or that even that make it work - i.e. the details that, if changed without understanding, make it worse. In other words, they can't prevent future mistakes the way that good commenting can. Weak code is self-documenting. The one case where commenting is unnecessary is when the code solves a problem everyone knows in a way everyone knows. If you're doing anything even slightly difficult or innovative, you need comments.
- "Comments can be out of date."
So can code, but that's clearly not sufficient reason to avoid it. Yes, comments can get out of date, but that doesn't make them useless. A good "why" comment can be almost timeless, unaffected by changes to the code short of eliminating the entire module including the comment. It's the weaker "how" comments that are most vulnerable, and even they might provide some useful information about intent. It's a rare comment indeed that's misleading enough to be worth less than zero, and even in that extreme-outlier case we should consider the positive value it might have had before it became out of date. When the same people who ignore the high probability and large impact of a bad rewrite make so much noise about the low probability and small impact of a bad comment, you know they're acting in bad faith.
Maintainable code is well commented. No excuses. Even if it's written in the clearest possible style, everything refactored and renamed to perfection, with copious tests, there will still be information about it that belongs in comments. It's a shame that so many developers - I won't call them software engineers because their ethos is the very opposite of engineering - even need to be reminded of that.