News for hackers. Stuff that matters.

A comment on Your Code is Not Self Documenting. Parent comment

Re:Your Code is Not Self Documenting by skybrian on Monday January 10, 2011 @12:55AM (#2087652)
Yes, there's particular style of code called "self-documenting." It's a good style and I recommend that everyone learn it. However, it doesn't do everything. It's good at explaining what happens and how it happens but not why. Comments are for explaining why. Without knowing the original programmer's intention, I'm still mystified.
[ Parent | on HN ]
Re:Your Code is Not Self Documenting by lelele on Monday January 10, 2011 @04:57AM (#2087994)
> Comments are for explaining why.

Awesome. I'd add "why not" as well, that is: why you discarded some alternative solution? That's very important especially when refactoring is involved. Some programmer could come by and think: "Why she didn't just do like this? It would have been much easier."

I find that explanations about discarded solutions is (almost) always missing from both comments and higher-level documents.

[ Parent | on HN ]