Commenting "why" (Score 2, Informative)

I've heard one person after another argue about how to comment and how much to comment, but what I've never seen is any kind of serious study attempting to measure what actually works best.

FWIW, in studies of the problems developers encounter in practice, one recurring difficulty is working out the motivation behind a given piece of code. This supports advice to comment why the code is written the way it is. See, for example:

• LaToza, Thomas D., et al, Maintaining Mental Models: A Study of Developer Work Habits, in ICSE '06: Proceedings of the 28th international conference on Software Engineering
• Ko, Andrew J., et al, Information Needs in Collocated Software Development Teams, in ICSE '07: Proceedings of the 29th international conference on Software Engineering

Both papers were coauthored by Robert DeLine and Gina Venolia of Microsoft Research.

In LaToza, 66% agreed that "understanding the rationale behind a piece of code" was a serious problem for them.

In Ko, "Why was the code implemented this way?" was the second most frequently unsatisfied information need among the developers observed.