About the Anticommentist Party

When we first learn to program, we're often taught that comments in our code improve the readability of what's there. This makes sense to a novice programmer because he has yet to really grok this arcane computer scrawl.

It's true that comments can aid in the process of learning a new language in the same way that understanding German poetry could be easier for a novice if they have a translation of the poem in their native language. The ultimate goal in learning a language is not to be able to speak it with an English-to-German dictionary on hand but rather, to not need such a learning aid.

Sometimes, it is argued that comments are useful for explaining very complex algorithms in a way that's more comprehensible to people. It is therefore argued that comment can help people understand the ways a code block can affect state, or the possible gotchas in the design.

But the very best programmers know to avoid compilcated code. Experience trains them to favor simpler designs that need no explanation to anybody with basic programming skills. They favor code reuse and compact, robust solutions that do not require much knowledge in order to use.

The times when code complexity necessitates comments are when the code itself should be reconsidered.

Every line of code written has the potential to hide a bug in the software. This goes as much for comments as it does for actual, meaningful code. Comments can distract the reader from important details. Large blocks of comments can obfuscate relationships that separated segments of code may have. The contents of the comments can break the flow of the reader's focus in comprehending the actual functionality of the code.

Declarations of intent may help people understand what the programmer wanted to do – assuming the programmer even understands the problem well enough to articulate it – but in the programming world, one's intent doesn't always line up with what they ended up writing.

When the bits finally hit the compiler, no amount of writing or reading the comments is going to do the work of debugging the final product. Being able to understand not what was said about the code but what is actually happening in the code is the only thing that can get the system working.

Experienced programmers know this and thus, tend to focus more on the actual code than on the comments surrounding it. They tend to reserve the act of describing their code for the documentataion and will leave simple, easy-to-follow code to express itself unambiguously.

When they're not a distraction, comments have the potential to be harmful to the understanding of a program. As software evolves to suit the turbulent demands of its users, the changing specifications and standards that it relies on, and other advancements in technology, comments often get neglected and go stale; describing old intentions or misunderstandings that do not reflect the code's actual or more correct behavior.

Inaccurate descriptions of program behavior in the comments does more harm for new programmers entering the project (if they bother to read and believe those comments). It can pollute their understanding or set bad expectations for other members of the team.

Because it's already difficult to maintain large code bases, it seems silly to make the code base unnecessarily larger by adding spurious text into the mix. If that dross also happens to be confusing, are comments serving their intended purpose?

Rather than cluttering a code-base with comments, it's better to give variables, functions and classes descriptive names, to learn to recognize common code patterns and to follow those recognizable patterns in the code you originate. When the code explains itself well, it cannot be changed without the explanation matching its nature. The better the code gets at describing itself, the less people will feel like they need to clutter it with comments.

Descriptive commit messages in source control also go a long way to providing the benefits of code comments without the risk of those descriptions also going stale and becoming deceptions instead of descriptions.

Most importantly, writing lucid tests (such as Unit Tests) goes a long way toward describing a software system's true behavior and design. By applying the above rules to the test code in addition to the production code, full, annotative, unambiguous descriptions of the software's behavior become apparent to anybody with a decent understanding of the programming language.

While there might still be a need for some comments in code, there is not as much as we're lead to believe. Many are taught that it's better to have tons of comments than none at all.

For reasons given above, the anticommentist party believes the reverse is true: It's better to have no comments than to maintain the code both in meaningful form and in comment form. It's better to favor clean, uncomplicated design than to write code that needs comments in the first place.