Many developers don’t like leaving comments in code. Among developers, the belief that “proper code should explain itself through code, not comments” is strong to the point of being a little excessive. Some of you may already be uncomfortable just from the title of this post.
I am in favor of leaving comments. Development is not something you do alone. The same goes for personal projects. It’s right to see the me of today and the me of the future as effectively different people. Leaving comments for the understanding of others belongs to the realm of kindness, and it is never excessive.
The three perspectives from which I consider comments useful are as follows.
📍 Comments are a guide.
Someone seeing the code for the first time may find it hard to tell what the code is. It’s best if the code explains itself, but no matter how declaratively you write it, there can be limits. In those cases a comment can serve as a guide that tells you where and how to start reading the code.
📍 Comments explain the history.
Every piece of code has its own history. It’s nearly impossible for code to stay in a perfect state. On the contrary, schedule pressure or business reasons can turn it into code that is hard to accept (from a third party’s point of view). But if a comment records why it ended up this way, the code can move from displeasure into the realm of understanding. And once it can be understood, it becomes possible to discuss how to improve it from there.
📍 Comments are a reference.
No matter how smart you are, code you’re seeing for the first time is hard to understand if it’s complex. If the codebase is large, it’s not easy even to get a sense of where to start. For cases like this, a comment can point to which document to read. By leaving links to documents such as UML diagrams, business explanations, and related modules, things that can’t be put into code, you can encourage learning about the codebase. This can also improve code ownership. Or it can be used as a tool for proper onboarding.
A comment left as a kindness to others, at the cost of a moment of hassle, can lead to productivity. If it takes root as the team’s development culture, it can also become training in commenting at an appropriate level.
With kindness, too much is better than too little. If a comment gets in the way of readability, you just delete it. If simple comments reduce misunderstanding and people feel the kindness, improvements can be discussed without anyone’s feelings getting hurt.
Actually, it doesn’t have to be comments. If information can be shared smoothly and communication is active, you don’t need to write comments. But if that’s not the case, how about starting with comments?
