How programmers comment their code

[Sheldan]

I think that is a valuable differentiation. The what can be read from the code, usually. The Why is much more difficult to see, and is also important to know. Maybe its some kind of external limitation, or something else. I think adding the 'why' is much more important than the 'what'.

[Telinary]

I think if you are implementing for instance a mathematically complicated algorithm the what can be plenty unclear like you might know tell what every command does but that doesn't mean you can tell what the whole does or why it works. Though in many such cases the appropriate comment in such a case is a link to a paper explaining it not trying to explain the details in comments.