this post was submitted on 28 Sep 2024
1151 points (99.0% liked)
Programmer Humor
32162 readers
691 users here now
Post funny things about programming here! (Or just rant about your favourite programming language.)
Rules:
- Posts must be relevant to programming, programmers, or computer science.
- No NSFW content.
- Jokes must be in good taste. No hate speech, bigotry, etc.
founded 5 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
I know some folks are joking about and dunking on this, but in modern times, I have justification. Call me lazy, but I have found myself writing out these comments and then letting the AI take over to at least give me a sketch of an implementation. Works reasonably well and saves me a lot of time and effort. Mostly I don't bother to remove them, though I usually edit them a bit.
On the other hand, there are factions within my colleagues who steadfastly insist that commenting is unnecessary and to some degree even potentially harmful, and that if you feel the need to comment your code, it means your code should be improved so that it's obvious what it is doing without the need for comments.
And your colleagues are probably correct with respect to this sort of «what it does» commenting. That can be counterproductive because if the code changes and the comment isn’t updated accordingly, it can be ambiguous. Better have the code be the singular source of truth. However, «why it does it» comments are another story and usually accepted by most as helpful.
People always cite this as a reason comments are bad. In 30+ years as a developer I have seen (and participated in) a lot of failed software projects, but not once has a mismatch between comments and code been the actual cause of the failure. Moreover, the same logic could be applied to the names of methods and variables ("if the code changes and the method and variable names aren’t updated accordingly, it can be ambiguous") but nobody ever suggests getting rid of that. At the end of the day, comments are useful for imparting information about the code to future developers (or yourself) that is too complicated to be adequately communicated by a method name.
I didn’t say the source of failure. I said a source of ambiguity. And having also been in the industry for decades, I have encountered it many times, where a junior programmer or somebody new to a project read some documentation and assumed a behavior which in fact did not match the current implementation. So you may have been fortunate, but your experience is certainly not ubiquitous.
With respect to variable names, I’d suggest those too should absolutely be updated too if the name is given in a way that adds ambiguity.
I’m not saying comments are bad; rather that bad comments are bad, and sometimes worse than no comment.