Ask HN: What if code comments were not supported?
7 comments
Good code should have some comments. Not for the "what" but for the "why".
This is correct. But I think it confounds a lot of people because “comments” are often overloaded. E.g. comments used for tooling and API-facing documentation are not always distinguishable from comments intended for maintainers.
The former is supposed to answer “what”. You’re describing the characteristics of a part of the elephant, from the perspective of knowing the whole elephant.
In the latter, “why” is what determines whether a code comment is valuable (or if the code under comment is itself questionable). If your comment needs to explain to maintainers (including future-you) what the code does, it’s a huge red flag. The most reasonable exceptions to that are: important optimizations that obscure understanding the code by reading it; you have to interact with APIs out of your control that force you to write hard to understand code.
The former is supposed to answer “what”. You’re describing the characteristics of a part of the elephant, from the perspective of knowing the whole elephant.
In the latter, “why” is what determines whether a code comment is valuable (or if the code under comment is itself questionable). If your comment needs to explain to maintainers (including future-you) what the code does, it’s a huge red flag. The most reasonable exceptions to that are: important optimizations that obscure understanding the code by reading it; you have to interact with APIs out of your control that force you to write hard to understand code.
I had some thoughts on this just a couple weeks ago, in which I outright said I think most code comments are harmful: https://twitter.com/eyelidlessness/status/144409690913665434...
That said, I don’t think barring comments would be helpful. As you described, presence/frequency of comments tends to diminish as code quality improves. More, clarifying what I put in the tweet thread: quality of comments tends to improve and reliance on low quality comments tends to drop.
But that’s a correlation with other positive factors. Enforcing that a hypothetical low quality code author cannot include comments won’t convey all of the other factors that would help them improve the code they write. It’ll just make their low quality code more opaque.
A better approach, in my opinion, is to treat comments as code smells in review/maintenance tasks. You can use this as an opportunity to interrogate the comments directly, and discuss the commented code secondarily. This gives you a chance to express, here’s an approach that might not need explanation at all.
That said, I don’t think barring comments would be helpful. As you described, presence/frequency of comments tends to diminish as code quality improves. More, clarifying what I put in the tweet thread: quality of comments tends to improve and reliance on low quality comments tends to drop.
But that’s a correlation with other positive factors. Enforcing that a hypothetical low quality code author cannot include comments won’t convey all of the other factors that would help them improve the code they write. It’ll just make their low quality code more opaque.
A better approach, in my opinion, is to treat comments as code smells in review/maintenance tasks. You can use this as an opportunity to interrogate the comments directly, and discuss the commented code secondarily. This gives you a chance to express, here’s an approach that might not need explanation at all.
It would not because comments are not what prevents people from writing good code.
My CS prof had a saying: Every comment is an apology.
Getting rid of apologies won't prevent people from making mistakes. Sounds like a cure for the symptoms and not the source.
Getting rid of apologies won't prevent people from making mistakes. Sounds like a cure for the symptoms and not the source.
the answer is simple: nobody would use it.
like what if there was a pc that wouldn't accept mice. I'm heavy hotkeys user and I wouldn't give up my mouse.
like what if there was a pc that wouldn't accept mice. I'm heavy hotkeys user and I wouldn't give up my mouse.
Just comment your dang code!
Seriously. Explain it at a level or two above the individual statements.
Seriously. Explain it at a level or two above the individual statements.
The better I get at writing clean code, the less comments I need to use. What if there was a "compiler mode" where comments were forbidden. Or maybe you are entitled to a limited number of comment words per file.
Could that spur programmers to write better code?