We spend little or no time teaching programmers how to write good comments.
This is surprising, when you consider how often “total lack of comments” or “poor comments” are cited as evidence that certain modules (or the programmer who wrote them) are the worst thing that ever happened to the technoverse.
I happen to think that there are much yuckier tech things than poor or missing comments in code. But I still think our general level of comment proficiency is lower than it should be.
Here is my attempt to raise the bar a little.
Why We Comment
Sooner or later, most interesting programming problems require a sophisticated mental model of a problem. Building these models is hard work, and once we have them, we are paid to share with our team (or our future selves).
The best way to share mental models with other engineers is Continue reading