Hacker News Reader

> Code comments document the why, not the how.

I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.

View on HN

So where would you document the "why" then? This is often the question I find most difficult to answer when reviewing code (including my own) -- after all, I can ferret out the what from the code.

There's nothing wrong with what your parent said.

If we are speaking of API documentation (i.e. function or module documentation): The "why" can't be explained here. It's at the caller side.

There are more rare cases where it's reasonable to document the implementation of a function because there's a particularly tricky section of code -- and documenting the "why" makes more sense to me here.

If you're able to ferret out the what from the code, then your code must be defect-free.

Otherwise we need to know via the comment (contract) what is the what, so that we can fix the bug (or even know that there is a bug).

Reply on news.ycombinator.com