Why Bad Comments Are Good, Actually

Ian Vanagas
Mar 11, 2022
5 min read

Everyone hates bad comments in code. They confuse us and slow us down. We have to do work to understand them, on top of the changes to the code we planned. Someone else’s bad comment causes us to do more work than we expected. This leads us to see comments negatively, and that is a bad mindset. Instead, we should see bad comments as opportunities.

Believing bad comments are a waste causes problems. When reading a bad comment, you might think “if other people don’t care about comments, neither should I.” This encourages you to write worse comments or none at all. By writing fewer comments, you encourage your teammates to do the same. This spreads throughout the organization, leading to fewer and worse comments left in the codebase.

This is bad news for individuals and organizations. Bad comments are better than no comments, and in a lot of ways, they are actually good. Without comments, context collapses. Less information is shared in the codebase, and every developer does more work to figure it out themselves. You and your team should write more comments even if they are bad because they always provide useful information.

Bad Comments Are Good

No matter how bad a comment may be, it still provides information. That information is valuable to yourself, your team, and the people reading the comments in the future. It provides context on the thinking that went into the code. The “why” of code, if you will

Every comment provides insight into the thinking behind the implementation. Bad comments and code come from incomplete thoughts. A bad comment can be your guide to understanding which methods and classes are strong, and others that need improvement. Methods or classes with bad comments likely come from someone without a strong understanding of requirements, context, or functionality. They are hints to check that code is good enough to rely on.

Judging comments is a skill that improves your ability as a developer. If you can recognize a comment is bad, it might be a sign you have the context to write better code there (or at least a better comment). See if you can rewrite the comment to better describe the functionality based on the context you have. Check with the person who wrote the comment to see if your changes are an improvement. This work helps others understand this code who revisit it in the future. Heavily used, poorly commented code is a prime area for improvement.

Bad comments provide an opportunity to improve your thinking. What you perceive to be a bad comment might be a good one you don’t have the information to understand. This is especially true when the implementation looks good. It forces you to think if what you're reading is wrong or misunderstood. This solidifies your knowledge. It can also be solidified in your team’s knowledge by updating the comment, changing the documentation, or talking about it in a meeting. A bad comment sometimes gives you and your team new knowledge when looked at in another light.

At a team level, bad comments can represent a failure of collective knowledge. Managers should be concerned when they see a lot of bad comments. It means the team either isn’t prioritizing writing comments or have a poor understanding of the code they are writing. This is a major problem. It should be a sign to spend more time developing context as a team. Team members must understand the “why” and “how” of the code to write good comments. Writing bad comments likely means they don’t have this context. The communication, incentives, and collective knowledge within the team needs to be improved, and better comments come along with it.

You Should Write More Comments, Even If They Are Bad

Bad comments provide a lot of information. Information on the context of the code, the knowledge of the developer, the collective knowledge of the team. They help you recognize when priorities changed, and where that needs to be reflected within the code. They indirectly help you practice writing better code by improving your judgement of code.

Bad comments are an opportunity. You shouldn’t be so scared of them. Comments are worth the effort to write even if they are bad or will be misunderstood by someone lacking context, as we’ve outlined. They help you improve both your thinking and your ability to write good code. As a manager, they help you understand your team's thinking, and improve the context they have. Recognizing and trying to improve bad comments improves your organization’s ability to perform well.

Bad comments allow future readers of your code context into your thinking. A future team might think your comment is bad after the collective knowledge of the team changed. Your manager might recognize they aren’t giving you the context you need to succeed. Someone else reading your code might learn something from your “bad” comment. Without comments, all of these opportunities are lost.

If you believe in the value of (bad) comments, you believe in the value of context. If you believe in the value of context, you might want to give Codex a try. Find out more here.

Remote work is the new normal. Start using Codex today.

Install Codex today to start making your engineering team more productive.

Install VS Code Extension

or download from the Visual Studio Marketplace