The hill that I will die on is that if you need to comment what your code is doing, your code is either a) bad and should be rewritten to be clearer, or b) the result of tricky, clever optimization that you needed to do after profiling.
Comments should tell readers why you're doing something, when it's not obvious based on the code itself.
Obviously, the best way to make code self-documenting is to wrap logic in a method whose name clearly describes its intended function. For one-liners however this can lead to overabstraction, and leaving a "what" comment can be entirely appropriate if the engineer decides it is. This cult-like behavior of engineers who think that well-commented code is some sign of weakness or unprofessionalism is beyond silly.
Absolutisms are a sign of a bad engineer, but I can give you the benefit of the doubt and not assume you're a bad engineer just because you employ such absolutist statements and use erroneously use them to judge code by oversimplified metrics instead of relying on deeper analysis.
Does this mean every line of code needs an accompanying comment? No, that is absurd. But what's also absurd is the amount of judgement and unwarranted extrapolation over this particular bit of code, and the general defensiveness which most people in this thread seem to be engaging in. I leave comments like this sometimes if I think it helps increase code clarity.
Oh the tasty irony.
Please review the Hacker News guidelines, especially this excerpt:
> Please respond to the strongest plausible interpretation of what someone says, not a weaker one that's easier to criticize. Assume good faith.
Whether a LLM coding model demonstrates understanding of unnecessary comments might be interesting, as would any differentiation in quality if my prompt asked for more or fewer lines of comments.
> Whether a LLM coding model demonstrates understanding of unnecessary comments might be interesting
I think it would be an interesting experiment, that sounds like a great idea for you to pursue. Make sure to sample a wide variety of models, and include a caveat that LLMs are not a source of truth regarding such matters, as they are simply providing probabilistic text completions based on prior training data.
Comments are good. I am a huge proponent of more comments over fewer comments. I have written functions where 80% of the lines are comments. But this is a bad comment for very simple to understand reasons.
https://www.perl.com/pub/2005/07/14/bestpractices.html/#7-co...
This style allows me to scan only natural language comments, generally rendered in a distinct highlight color, to get a high-level view of what the code does. My colleagues have rarely followed the same idiom, but my code has been well-regarded everywhere I've been.
When you do this, there are occasionally times where you wind up with a single line that isn't grouped with the others, and to be consistent the easiest thing is to insert a comment like the one that started this thread.
However, I've adapted this style over the years to avoid any hint of redundancy because some people feel so strongly that they will fixate on it and decide you're a terrible engineer for this one tiny detail. It's easier just to work around them.
You can have your preferences all you want and that's great, but when you start passing irrational judgement about the value of someone's code just because it's liberally commented, your perspective becomes less respectable.
I'm sorry, that was not intended to be received as a demand, I edited my comment to hopefully clarify.
> You can have your preferences all you want and that's great, but when you start passing irrational judgement about the value of someone's code just because it's liberally commented, your perspective becomes less respectable.
I didn't say anything about the value of your or anyone's code other than that obvious comments don't add any to me. (I do tend to find it funny when a comment manages to obviously contradict the code that it's about, but here that's not the case.) My point was more that comments are more useful to me when they're non-obvious. See, again, the data structure example.
No. You have "well-commented code" completely backwards. This is not it.
// This is the end of my reply.