Comments Are Inevitable - Tom Moertel’s Blog

Tom Moertel’s Blog

Home<br>About<br>Archive

Comments Are Inevitable

By<br>Tom Moertel

Posted on August 14, 2026

Tags: code, comments, beyond clean code, clean code, good code, nature of code, purpose of code, source code, definitions, theory, philosophy, engineering culture

(This post is part of a series of posts on good code.)

One of the arguments floated in the book Clean Code is that “if our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all.” In other words, comments are needed because at least one of two conditions is true:

We programmers lack the talent to express our intent without using comments. (We have failed.)

We programmers lack the means to express our intent without using comments. (The designers of our programming languages have failed.)

In my earlier post on the subject, I argued that the first condition is false. My argument was simple: The humans reading our code need to know not only what our code does but why it does what it does and why we chose to implement what it does in the way that we did. Since natural language is the most effective way to express this all-important “why” information about our intent and coding decisions, skilled programmers often prefer to use comments for this purpose. After all, that’s what comments are for: to let us speak directly to our audience in natural language.

In this post, I will argue that the second condition—that the designers of our programming languages have failed us—is also false. My argument is even simpler. Just one paragraph:

If the designers of our programming languages created an ideal syntax for communicating “why” information, what would it look like? To be worth using instead of comments, that ideal syntax would have to rival the expressiveness of natural language. In its most perfect form, it would be natural language. But then that ideal syntax would be comments.

Thus comments are inevitable.

This fact, however, does not imply that all comments are necessary or even useful.

Every programmer knows that bad code is often replete with bad comments.<br>Rather, what this fact implies is that, if you are providing your code’s audience with what they need to know, and you are doing it in the most effective way, your code will not only have clear logic but also compelling comments.

That’s because logic alone does not suffice to clearly communicate what your audience needs to know.<br>Its syntax is too restrictive to be a good vehicle for carrying natural language.<br>So you can either contort your logic in an attempt to create more opportunities to shoehorn natural language into function and variable names, or you can speak to your audience directly through comments.

You see, if you are unafraid to use comments when they are the best means of communicating to your audience, you will have no need to contort your code’s logic into a crude approximation of natural language.<br>Your logic can thus be a simple, straightforward expression of your solution and its problem domain, with no extraneous structure or distractions.

My advice, then, is to set aside dogma like “comments are failures” and do what actually makes sense:

Let your logic be a simple, straightforward expression of your solution and its problem domain.

Pick informative (but not unwieldy) names where your logic allows.

If your audience should know more, tell them directly using comments.

So, when you are writing code, if you need to let your audience know something nontrivial that is best expressed in natural language, use a comment.<br>Do not grimace.<br>Do not feel shame.

Instead, rest satisfied in the knowledge that your code is clear and compelling.<br>In the end, that’s what matters.

Please enable JavaScript to view the comments powered by Disqus.

Site proudly generated by<br>Hakyll