Hacker News Reader

Comment by noonespecial | Hacker News Reader

The code itself is the "truth". The comments are commentary.

  //Set x to be 4
  x=5;

Which would you rather have bold and jumping out at you when skimming? Comments can be wrong because tweaks happen.

View on HN

To me, this is a terrible example, because it's a useless comment. The comment should explain what "x" is for, not what you're doing to it. I you have a comment about what "x" is for, which becomes more important? The assignment, or the explanation?

Shrug. Most of the code I have to deal with regularly is primarily commented with profoundly unhelpful, often blatantly incorrect nuggets such as this. Forever what and never why. It seems better if it just faded into a fossilized archeology that only needed to be Gandalfed in the most dire circumstance.

In my situation, making the comments "stand out so that people will make better ones or fix them" seems optimistic to the point of being naive. We may in the end be down to the old "what should be" vs "what is".

If you have to explain what x is for with a comment, maybe x is a bad name in the first place?

"x" is not always something which can be easily or fully explained in one to four words. And anything over four (short) words is typically getting too cumbersome as a variable name.

I'm sold on the argument in the article, I'd rather have the comment jump out and be deleted than see it sink into the background and remain.

I'd much rather have the `x=5` jump out at me, because the example comment is entirely redundant. However, if the example was

    // removing this will cause a segfault because ...
    x=5;

then I would rather have the comment jump out at me.

"I would rather have the comment jump out at me."

Really? The only time you need to know that removing that line will cause a segfault is if you are going to remove that line; but, if you're going to remove the line, you're surely going to check the comment above it, even if the comment doesn't jump out at you. Even an important comment is still irrelevant except when you are looking for clarification about the code it comments on; so I don't think it ever makes sense for comments to be emphasized more than the code.

One of the points made by the article is that if syntax highlighters made comments jump out at people, they wouldn't be so eager to comment unnecessarily (like in your example) since it'd start looking bad. It's a solution that fixes two problems in one go.

Having the comment bolded would be excellent! It would immediately highlight that the comment is both useless and incorrect, and should be removed. The only comments that should remain are those that you really don't want to miss.

Reply on news.ycombinator.com