Keep It In Their Heads

Comments are not good or bad per se, but they contain some risks and writing them is expensive. People don't write comments because they load up their head to learn enough to write, then their head is already loaded and they don't need to write. Just when to spend the time to copy the head contents very slowly and pretty poorly into text/figures is the tough question. Energy is better spent revising the code than commenting it.

A similar statement could be made for requirements documentation, analysis documentation and other pieces of documentation.

This page started from ToNeedComments and don't forget to see SelfDocumentingCode.