Hacker News Reader

Comment by eru | Hacker News Reader

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.

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

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.

To increment x

Why do you need to increment?

Because it needs to be bigger.

Then make it times 2. Or add 5.

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.

Reply on news.ycombinator.com