Hacker News Reader

Comment by fleitz | Hacker News Reader

Learn to read code instead of comments. It's super straight forward C.

What the code is doing is clear. The why (and especially the `why not') could benefit from some commentary.

I wish more programmers understood this concept. Yes, we can read the code for the what, which is why we don't need you to tell us you are adding 2 to X. Why is a different matter altogether, and that is where a comment can shine light on the scenario.

Thanks for elaborating on my thought. The `why not' is often as important (or even more important!) then the `why'.

By `why not' I mean, briefly explain what other alternative approaches there were, and why you chose the trade-offs you went for, instead of some other set.

To me it ruins the surprise, uncommented code is like an uncommented novel, once you've grok'd it the whole thing starts to make sense.

Comments are like coles notes.

It's good as professional courtesy but for personal projects... seems like a waste of time.

>it ruins the surprise

Huh? In the first place, I do NOT want any surprise at all.

Until you go back to it in a year's time and can't remember any of the reasons for your design decisions.

Besides, I genuinely find myself hilarious so the attempts at pithy commentary tend to make the whole "christ what was I thinking" part of looking at my old work less painful.

A novel is nothing but comments. The code was already executed in the author's brain.

Exactly that

Coders: don't give me any BS like x = x + 1 /* Increment x */

Rather, tell me, if it's not obvious, WHY are you doing that

To increment x

Why do you need to increment?

Because it needs to be bigger.

Then make it times 2. Or add 5.

There should rarely be any comments on why x is being incremented unless there is something particularly clever about why. Commentary should be reserved for program blocks where something non-obvious is happening or where something obvious is happening for non-obvious reasons, IMHO.

I read c or assembler code like I read a newspaper, but comments are needed even in my own code to understand the higher lever design.

I shouldn't have to do a linear scan of the code to find what I'm searching. Like a book has headlines, code should have comments to indicate what's what.

Reply on news.ycombinator.com