is Ben Rudgers

Documenting versus Commenting

This post was written as a response to this thread on HN.

I am reading two introductory computer programming texts simultaneously, and have been thinking about comments recently, and your post brought them to a head. Structure and Interpretation of Computer Programs gives example code with no comments. Quite reasonably questions of commenting style are left out for narrative flow – magic is hard enough, no need to bring in religion.

On the other hand, How to Design Programs has an explicit commenting format. It’s design method formally starts with comments.

The question which has been kicking around my mind is, is it helpful to think about commenting and documenting as two different types of activity? And here I am inclined to be a splitter. Documentation describes the unit from the outside. It addresses the question, how do I use this black box? Comments address a different set of questions about the implementation, e.g.why did I use an array instead of a hash, or that a code block needs dekludging. Commenting is providing information that is irrelevant to the use of the function.

Yes, they slide together. A kludge may make a code block perform so poorly as to make it unsuitable for the user. My thought is that it may be helpful to think of commenting and documenting as separate mental activities.