The discrepancy between theory and practice is greater in practice than in theory. This observation definitely applies to comments. In theory, the general idea of commenting code looks commendable: to give colleagues a detailed explanation of what is happening. What could be more useful than providing useful information? But in practice, comments often do more harm than good. Like any form of writing, writing comments requires skill. This skill largely involves understanding when not to write comments.
If the code is written with syntax errors, compilers, interpreters, and other development tools will definitely object. If the code is functionally incorrect, most of the errors will be identified through review, static analysis, testing, and real-world deployment in a commercial enterprise. And what about comments? In the book “The Elements of Programming Style” (Computing McGraw-Hill), Kernighan and Plauger note that “a wrong comment has zero or negative value.” And yet, such unworthy comments thrive in the code, much to the envy of all kinds of errors. They constantly distract attention and misinform. They serve as an unnoticed but constantly active brake on a programmer’s thinking.
What can be said about comments that are not technically incorrect but do not add value to the code? Such comments are just noise. Sometimes comments merely repeat what has already been said in the code in natural language, that is, they parrot without conveying anything new to the reader; such repetition does not add weight or correctness to the code. Commented-out code does not execute, so it is useless both for reading the code and for its execution. Moreover, it becomes outdated very quickly. Comments regarding version numbers and blocks of commented-out code are attempts to address version control and code history issues. Such issues are resolved (and much more efficiently) using version control systems.
The prevalence of meaningless and incorrect comments in code prompts programmers to simply ignore all comments, either skipping them while reading or turning off their display. Programmers are inventive people and will find ways to bypass anything they perceive as harmful: collapsing comments, changing the color scheme so that comments are the same color as the background, or deleting comments with a specially written script. To save the code from such an inappropriate application of programmers’ creative abilities and to reduce the risk that someone will miss truly valuable comments, comments should be considered part of the code. Each comment should have some value for the reader; otherwise, it is just garbage that needs to be removed or rewritten.
What kind of comment can be considered valuable? Only a comment that conveys something that the code does not say and cannot say. If a comment merely explains what the code fragment should independently convey, it indicates the need to change the structure of the code or the adopted coding conventions so that the code speaks for itself. Rather than commenting on insufficiently precise method and class names, it is better to rename them. Rather than commenting on blocks in long functions, extract them into small independent functions whose names reflect the purposes of these blocks. Strive to convey as much information as possible through the code. If you cannot describe everything you would like to with code alone, a comment may be appropriate here. Comment on what the code cannot say, not just on what the code does not say.