Against Comments

Commenting source code, inserting natural language explanations, is dangerous.

If you are English, and try to speak French, but do not think in French, then no matter how many French sounding words you blurt, you speak poor French. To understand and use French properly, you must think in French. Using English prevents true understanding. If you are a programmer, and do not think in the programming language, then no matter how many comments you read or write, you use the language poorly. You must think in the language. Using comments prevents true understanding. Comments suggest poor programming.

A computer obeys the code, not the comments. When comments differ from the code, the comments are wrong, so should not be there. When they reflect the code, they repeat what is expressed, so should not be there. If an accurate comment is not updated when source code is modified, it changes from unnecessary to incorrect. Further modifications, if made by someone who reads the comment, not the code, will probably be wrong. A comment is at most a mechanism to increase the risk that maintenance of a correct program will fail.

Documentation is usually necessary. It specifies how a program should operate. The source code is a translation and extrapolation of the documentation from natural language to programming language. The translation should be complete; bits of natural language left in the code as comments imply the programmer could not translate satisfactorily. When translating, it may be necessary consider detail omitted or expressed vaguely by the documentation, or to reconsider items which, as documented, cannot be well expressed in the programming language. Such matters suggest the original documentation is flawed. That documentation should be modified.

The absence of comments requires high quality, well expressed code. It should be obvious what is going on to someone who is fluent in the language. Every item should be named for its purpose. The code should be elegant, clear and concise. It should be written to be expect a reader to think, know the language, read the documentation, search the source code, understand the operating environment, be educated in programming techniques, be professional. The presence of comments permit the absence of these standards. Comments imply lazy programming and poor quality code.

There is an exception. An excellent comment will translate code into explanatory natural language, so people who do not understand a programming language properly can grasp the code from the comment. Comments may be safely included in examples.

Comments, useful in example source code written for beginners, otherwise discourage correct understanding of a program and its programming language, increase the risk that software maintenance will fail, reduce the validity of documentation, discourage well expressed code and encourage lazy, poor quality work. Comments are dangerous, and should be avoided.

2004