alt Hacker Newsas others have pointed out, the reality is not this. id go further and say almost all comments are evil.
Excuse me if I am harsh, read the damn code. If you do not understand the language, that is a skill issue. If the code is confusing, then the code is bad and no amount of comments will ever change that. Professional engineering isnt an intro to databases class.
I am excusing language conventions which may have comments as part of its idiosyncratic nature.
Replies
If you are only encoding intent through "self-documenting code", and not with comments, then you are purposefully not using all the tools at your disposal to encode meaning as efficiently as possible.
Imagine a complicated section of application logic. You could break it up into 5 separate functions that document their intent semantically, thus blowing up the LOC by 5x, or you could write a short comment explaining the intent in natural language. What's more effective? I'd argue it's always going to be using all the tools at your disposal when and where it makes sense to use them, whether that is comments or self-documenting code.
Clean code considered harmful.
No, really: comments should be telling you what the code shouldn’t or physically can’t. Code is for execution and the exact details of what and how; it has no business knowing why or why not and that’s where comments are required.
The code tells you what the code does. It does not explain why it is doing that, and not something else. That is, among other things, what documentation does, and that includes comments.
"If the code is confusing, then the code is bad and no amount of comments will ever change that."
I've worked on a lot of terrible legacy code in my career and I'm very thankful for the comments that others have left. This is becoming less necessary now that LLMs can explain a project, but comments have historically been a godsend in bad code.