Hacker News Reader

Comment by kelnos | Hacker News Reader

That's not well-commented code, that's just noise. When you are calling a function named "read_csv()", you do not need to add a comment that says "Read the CSV file". These sorts of comments make code harder for humans to read.

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.

View on HN

I agree that there should be "why" comments. Those are great to have in any codebase. However, that does not preclude descriptive comments.

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.

Every word of the comment is in the code except "the". That level of redundancy is always bad. Yes, always.

A well-placed comment serves as an anchor for the eye when skimming large amounts of code, and provides a sanity check. This is something you would come to appreciate when working in certain environments.

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.

"Absolutisms are a sign of a bad engineer"

Oh the tasty irony.

I didn't say always. I made a general statement and avoided absolutist terms. "Are" is not an absolutist term if you charitably interpret my comment and I'm happy to clarify if you need it, however I don't need to append every comment with a disclaimer so that people like you don't respond with meaningless criticism towards some straw man.

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.

Reply on news.ycombinator.com