Hacker News Reader

Comment by davidkunz | Hacker News Reader

I actually like that comments are usually toned down. They don't cause runtime exceptions and compiler errors, they don't disturb the program flow, they are not the cause of the bug I'm trying to fix. Just some hints to help me understand the code. For really important comments you can still use `TODO`, `FIXME`, etc. which most editors highlight more.

View on HN

Maybe we editors should include a REALLYIMPORTANT flag too. But the fact that I never thought about it before reading that article suggests it's not really important.

Agreed. Maybe I've had this wrong most of my programming career, but comments are usually for explaining the "why" of code if the code isn't that obvious by itself (and if this is the case, I usually try to refactor it first). It's rare that my comments ought to take precedence over the code itself.

If I do have something REALLYIMPORTANT (which is exceptionally rare), I plaster it all over so that it's practically not missable (esp. in code review). Sure, highlighting _that_ comment might help a bit during development, but I really don't think that use case is worth highlighting _all_ code in that case. But it could be a 'nice-to-have' for syntax highlighters.

How about a one line comment that summarizes what the block of code directly below does, in order to avoid the need to run an interpreter in your head while skimming code to find what you are interested in.

That little bit of extra information, which only takes a few seconds to type, can save a lot of people a lot of time afterwards.

I do this, and add any addition "why" or other needed detail indented under the first summary commented line.

You mean when the code is too long, and you summarize regions of it for easy location?

Making the comment large is good enough for that. But a really different tag may help here.

Reply on news.ycombinator.com