You Absolutely (Do Not) Need to Comment Your Code

Of course you don’t need comments in your code.

But your future self appreciates explanations: What is this nested loop good for? What is its purpose? Comments provide context, and shortcuts for understanding: “you don’t need to read this, just think of it as …”

Once you explain what the purpose is, suddenly you may also find a way to express the intent clearly in code.

There’s this weird back and forth in one’s writing: between the urge to comment in order to clarify, and figuring out ways to make the code itself clearer based on these comments, thus making them obsolete.

Recognizing that there’s this pendulum that swings at all is the key insight.

And that you are its first mover:

Nothing happens without your attention.


Writing comments is part of communication in our practice. But it’s not the only one.