original article

Now then, on to the “proper” use of comments.

1. Write out what you are planning to do in English…
2. Make a copy and label it “documentation.”

3. Go back to the original, fill in all of the logic…label it “source file.”

I’m reluctant to discourage people from writing both specs and comments, but I think that advice needs to be taken with a grain of salt. One of the most common causes of error in programming is having two copies of the same thing that get out of sync over time. This “thing” can be specs vs. comments in your example, variables in a program, or cached disk blocks in a system. Maybe I’m especially sensitive to this sort of problem because this last example is pretty much my specialty (or maybe it’s the other way around) but alarm bells go off for me whenever someone suggests duplicating something without specifying how the copies will be kept in sync.

IMO comments should be complementary to what’s in the spec, not a copy. Explanations of how the program is written, especially those that would apply regardless of module structure or implementation language, belong in the spec. Explanations of how the code is written, that might be hard to understand except when the explanation and the code are close together, belong in comments. Putting information of either type in the place designated for the other is IMO a mistake.