Why do we need code comments? I would not be surprised if your first answer is, “We don’t.”
I get it. Senior developer after senior developer has taught us that “comments are bad.” And we cheerfully nod our heads, saying, “I am smarter for not using them.” We grin smugly when we see one of our juniors make the “mistake” of using comments in their code.
But as much as we sometimes abuse them, we still need comments.
I know comments don’t affect the code’s behavior. I understand how they can get stale and stop making sense. I am all for writing clean code, and I do my best to ensure my variables, methods, and class names describe their intent as accurately as possible. If I see dead code lying around in the comments for a while, I delete it.
But here is the bottom line: we need code comments because there are some things they do better than plain code. Here’s why.
1. Comments Are a Lightweight Way to Let You Experiment
The first place where code comments shine is in experimentation. Picture a time when you were trying to figure out one of the more complex bits of your application. Perhaps you were dealing with a tough query with multiple subqueries. Or you may have been trying to understand a multi-loop algorithm with many conditions. You were looking at this code and thinking, “There must be a better way.” Take the example below:
var joined = "";
foreach (var item in items) {
joined += ",";
}
return joined + "!";
Not a bad little algorithm, but it can probably be cleaner. So I’m going to comment out the code and experiment with a slicker version:
//var joined = "";
//foreach (var item in items) {
// joined += ",";
//}
//return joined + "!";
var joined = string.Join(',',items);
return joined;
I have my slick version ready, but then I run my unit tests and one is red! How? I look at the commented-out version and notice ‘joined + “i”;’ on the last commented line. Ah, I forgot to add the exclamation mark.
The comments in this example gave me a low-risk way to quickly try out something new in the code. Yes, I could have solely relied on my unit tests and eventually would have figured things out. Perhaps I could have scrounged around in my version control for what I deleted. But simply commenting it gave me the fastest feedback loop when experimenting. With commenting, any mistakes will stare you in the face when you try something new.
2. Comments Let You Exhibit Without Getting in Your Way
Code is rigid. It often requires strict syntax or it will not let you get anything done. This can be particularly annoying when you are trying to sort out multi-step problems and you want to spit your thoughts out on how you are going to tackle the issue. What I often do is pseudocode my strategy like so:
void doSomething(InputModel input) {
//find correct Customer
//make Customer preferred
//check for fraud
//send email to customer
//add "customer preferred event" to logging context
}
Putting my strategy in the comments lets me focus on the problem I am solving, not the syntax. In fact, many times I don’t remember the exact class or method I need. I don’t want to distract myself by hunting down the elusive class, so I just mark it in a comment and go on my merry way. Keep in mind, we are not paid to write code we are paid to solve problems.
Putting your strategy in comments can be especially great while pairing. Your pair partner monitor your current progress and take over. It’s also useful if you are working with a developer new to your team who’s still trying to grasp the codebase. You can guide them to “fill in the blanks” and show them the overall plan without breaking the codebase.
3. You Can Generate Code Documentation With Comments
You need comments for documentation, but not in the traditional “why did you put this comment here instead of naming your variable better?” sense. I’m talking about nicely rendered docs that can link to other pieces of documentation Wikipedia-style and let you explore the code.
Many languages have the ability to turn specific comments into rendered documentation. This gives you a quick and easy way to give a clean set of docs to your users or other developers. The comments are also near to the code, so you can update them as needed. For example, documentation-generating comments can turn this:
into this:
While I do not recommend making this your only source of documentation, it does give you an easy to way to start documenting your system to folks outside your team. This is especially useful if you are making a library. Developers very frequently need to see some form of documentation in your library as they are coding, based on the specific class or method they are using.
4. Comments Explain Why You Wrote Something
We now come to one of my favorite reasons for using code comments. Many times we need to do things in our code that are…out of the ordinary. Perhaps we have a really complex algorithm that no amount of “proper naming” will make self-explanatory. Maybe we have to put in a non-obvious workaround for a quirk in the system. The quirk may even be in a different class altogether.
Comments let us easily relay that information in a way nothing else can. We can use comments to explain why we did something, right there, as the developer is trying to figure out what is happening in our code. Take this example:
void DoSomething(SomethingInput input) {
var customer = mediator.execute(new FindUserByIdQuery(input.customerId));
customer.makePreferred();
mediator.execute(new SendCustomerPreferredEmailCommand(customer));
//we need to block because the inventory system is not wired up correctly,
//so it sometimes reads inaccurate Customer information.
blockInventoryWhileCustomerIsProcessed();
}
We needed to be clear why we are doing something out of the ordinary, so we explained our reasoning. Note that we did not explain how we are doing it; we let the code handle that. Here is another example:
//With this method signature we clearly see this input type is only for this method
void doSomething(SomethingInput input) {
//by using a mediator, we ensure we wire up the appropriate transaction, logging
// and Unit of Work.
var customer = mediator.execute(new FindCustomerById(input.customerId));
//we are using healthy encapsulation, letting the Customer entity do most of the logic.
customer.makePreferred();
}
In this one, I have turned my code into an instructional tutorial for developers new to the team. I explain almost every line. I don’t recommend using this method everywhere, but having some instructional areas within your code can be a great way to onboard new team members.
Now, Discern for Yourself
Code comments get a bad reputation. I get it: there are many ways to abuse them. But that doesn’t change the fact that they still can be a great tool in your toolbox. Don’t let dogma dictate your comment usage. Use your wisdom and take advantage of code commenting to easily experiment and explain your thought process to your teammates.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
