As is often the case on my website, I like to write articles in response to student questions. This time around, I got a question about priorities when it comes to coding. For example, is it more important that code is readable or correct? Naturally, I won’t open that can of worms today, but I will talk about a tangential discussion that came out of that question: why I comment code as a last resort.
Normally, when I write an article like this, I sort of dump my thoughts for a bit. Then, I go back and edit it up until it is nice and clean. This time, I won’t be doing that. Instead, I’ll be sharing my opinion as I shared it with the student with limited reasoning—just some general tips.
After that, I’ll share a ton of community perspectives with varying degrees of support for commenting code. Finally, I’ll wrap up all the views with my takeaways. Sound fun? I hope so!
Table of Contents
I Comment Code as a Last Resort
When I first learned to code, I was just 18. At the time, I had learned that commenting code was a good thing and that I should do it as often as possible. As I continued in my coursework, I received dozens of positive comments on my coding style which only reinforced the behavior.
Here’s what a piece of my first program looked like:
/* Returns the current cash balance for the the account
*/
public double getBalance() {
return balance;
}
/* Adds amount to account cash balance
*/
public void pay(double amount) {
balance = (balance + amount);
}
/* Returns the current minute balance for the account
*/
public int getMinuteBalance() {
return minuteBalance;
}
And, here’s what code looked like in my senior project:
/**
* Start device discovery with the BluetoothAdapter
*/
private void doDiscovery() {
if (D) Log.d(TAG, "doDiscovery()");
// Indicate scanning in the title
setProgressBarIndeterminateVisibility(true);
setTitle(R.string.scanning);
// Turn on sub-title for new devices
findViewById(R.id.title_new_devices).setVisibility(View.VISIBLE);
// If we're already discovering, stop it
if (mBtAdapter.isDiscovering()) {
mBtAdapter.cancelDiscovery();
}
// Request discover from BluetoothAdapter
mBtAdapter.startDiscovery();
}
Clearly, I liked to comment code. I used to add a little explanation to nearly everything I wrote, and I was regularly praised for it.
Then, I went out into the industry, and I found that the coding landscape was a bit more complicated. Code was extremely dynamic, and requirements changed by the day.
Naturally, these nice comments quickly turned into a minefield. If I wasn’t diligent when updating code, I’d find myself leaving comments unchanged. Later, those comments would come back to haunt me. Or worse, they’d confuse someone else.
Now, I find myself in the camp that code should be largely self-documenting. In other words, variable and function names should be descriptive. Likewise, code should be more modular and free of side-effects. As a result, more recently, my code looks like this:
/**
* Generates an HTML list item from some text.
*
* @param text
* the text to be listed
* @return an HTML list item
* @requires |text| > 0
* @ensures [an HTML list item is generated in the form
* <li>text</li>]
*/
private static String generateListItem(String text) {
assert text != null : "Violation of: text is not null";
assert text.length() > 0 : "Violation of: text is not empty";
String listItem = String.format("<li>%s</li>", text);
return listItem;
}
/**
* Generates an HTML link from some text and a url.
*
* @param text
* the text to be highlighted
* @param url
* the link to apply to the text
* @return an HTML link element
* @requires |text| > 0
* @ensures [HTML link is generated in the form <a href="url">text</a>]
*/
private static String generateLink(String text, String url) {
assert text != null : "Violation of: text is not null";
assert url != null : "Violation of: url is not null";
assert text.length() > 0 : "Violation of: text is not empty";
String link = String.format("<a href=\"%s\">%s</a>", url, text);
return link;
}
Well, actually, there’s a lot of stuff I don’t typically do here; this was for a course that heavily relied on design by contract. That said, I do like to break code up into methods as much as possible. Then, I only document the methods using comments that can be converted into an API like Javadoc. In other words, I avoid inline comments whenever possible. After all, they’re the least likely comments to be updated.
Of course, I prefer to stay in the realm of Python where code is a bit more readable by default. Perhaps in that space, I don’t need as many comments. Here’s a sample of what that typically looks like:
def get_clean_data(tables: dict) -> pd.DataFrame:
"""
Assigns appropriate types to columns. For example, this method
converts the timestamp column to the appropriate Python data type
datetime.
:param tables: a raw dictionary of iMotions data for a participant
:return: a pandas DataFrame of the iMotions data
"""
data_table = tables[DATA]
header = data_table[0]
data = pd.DataFrame(data_table[1:], columns=header)
data[TIMESTAMP] = pd.to_datetime(data[TIMESTAMP], format=TIME_FORMAT)
data[FIXATION_SEQUENCE] = pd.to_numeric(data[FIXATION_SEQUENCE])
data[FIXATION_DURATION] = pd.to_numeric(data[FIXATION_DURATION])
return data
At the end of the day, I’m not here to argue my position. Instead, I thought it would be more interesting to sort of plot my trajectory, share some of my code, and talk about what our community believes is the best way to handle comments. In the next section, we’ll talk about why I think exploring beliefs in the tech community is important.
Beliefs in the Tech Community
One of the things I love about being in this field is the diversity of beliefs that people have around particular aspects of programming. For instance, everyone in this field has a favorite programming language or a favorite development tool.
Naturally, these preferences are rooted in beliefs around the benefits and implications of a particular language or tool. For instance, I advocate for the use of version control because I believe that it helps developers rollback software when a major bug is released—among a dozen other benefits.
Unfortunately, these beliefs aren’t always rooted in reality. In fact, many developers hold beliefs based on experiences, rumors, and ideology. That doesn’t make their beliefs invalid; it just means that they’re unlikely rooted in scientific research.
For example, in the past, I taught a course where I was supposed to tell students never to use more than one return statement in a method. What is the logic behind that? Are there any benefits to following this rule? These are questions that I don’t know the answers to, but I guarantee anyone reading this has their own thoughts on the matter.
That’s fundamentally the problem, right? Our field has become tribal in the way folks form factions around these different beliefs. You’ll find some people who swear that commenting code is not just a good idea, it should be done on nearly every line. On the flip side, you’ll find people that believe code should be strictly self-documenting; not a comment in sight.
Of course, these beliefs likely fit more on a spectrum as everyone has their own opinions. For example, I’ve read that commenting should only explain the “why” and never the “what” or “how.” Alternatively, some people, like myself, prefer to limit comments to API documentation only.
With all these beliefs floating around, how can anyone possibly make sense of it all. Well, I figured I’d take some time to at least condense some of the beliefs I’ve seen around the internet, so you can make an informed choice for yourself.
In the following section, we’ll begin breaking down the different types of commenting beliefs.
Beliefs Around Commenting Code
When it comes to summarizing the beliefs of folks in the community, I had to come up with a few categories of beliefs. There were probably a dozen ways to do this, but I settled on categories related to the amount of comments that seem to appropriate—going from positions that advocate for the least amount of comments to positions that advocate for the most amount of comments. With that said, let’s get into it!
The Belief that Comments Should Be Used as a Last Resort
To kick off this list, I figured I’d share some community thoughts on the belief that I hold: comments should be used as a last resort. This appears to be the most popular belief, at least according to the various Google searches I ran.
When I was looking for people with this belief, I started by using the search term “commenting code is bad” which led me to an article by Jeff Atwood.
Now, I hesitate to share a resource by Jeff because I think he’s had a lasting negative impact on our community with the creation of StackOverflow. In fact, my website is largely an attempt at outranking StackOverflow in certain search terms, so folks can find more compassionate content.
That said, I think Jeff had a ton of great things to say in this piece. For instance, I really liked the following paragraph:
While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.
Coding Without Commentsby Jeff Atwood (July 24th, 2008)
To no surprise, Jeff is not the only one who holds this belief. In fact, a similar article by Peter Vogel popped up for the same query. In this article, Peter makes the following argument:
Based on those three facts, my claim is simple: your code is going to communicate to the computer and should also communicate to whoever maintains the code (who may be you, three months from now). To make life easier for the next developer, code should be written and rewritten to be as obvious as possible. What’s left for comments to do is explain what the compiler doesn’t have access to: why the code is there. Adding comments to explain how your code does its job — which (I think) some readers were recommending — is not the solution. It’s just adding more cost.
No Comment: Why Commenting Code Is Still a Bad Idea
Again, the argument isn’t that comments are inherently bad. Instead, it’s that comments come at a cost and that they should be used only when they make sense (i.e. to explain why the code is there).
The Belief that Comments Should Signal Intent
Perhaps the next step up from leveraging comments as last resort is understanding that code can never be self-documenting. Therefore, comments should be used to signal intent. This particularly ideology comes from Jason McDonald, a regular in the Python community, in his article titled “To Comment of Not To Comment.” In this article, he explicitly refutes three common arguments that come from folks like me who comment as last resort:
- Comments get outdated
- Comments create line noise
- Comments take time
Instead, Jason advocates for a more empathic form of code commenting in which he explicitly states the following takeaways:
– Any comment should describe what you intend the goal or outcome of a section of code to be. This is true, regardless of the frequency or density of your comments. Comments should never restate the functionality of the code.
– I believe a good litmus test is to imagine removing everything but the comments. Do you have enough information to completely rewrite the program? Furthermore, are the comments language-agnostic that they’d be equally useful if you switched from, say, Python to Java?
To Comment or Not to Comment
I think one of the most compelling arguments against my personal style is that code is not self-documenting. As a consequence, if commentless code contains bugs, how is the reader supposed to know that’s not the intention? It seems the “Commenting Showing Intent” framework solves for this issue.
The Belief That Comments Should Be Used Liberally
If we take Jason’s framework a step further, we’ll find where I was when I first learned how to code: comments were everywhere. In this ideology, comments should be used as often as possible to not only signal intent but to explain what the code is doing.
The first place I saw this advocated was by an author named B.J. Keeton who shared the following tenets for commenting:
– Make them brief
– Keep them relevant
– Use them liberally, but not to excess
How to Comment Your Code Like a Pro: Best Practices and Good Habits
As it turns out, this is actually a fairly common belief in the community. I suspect it’s because developers have quite a history of not commenting their code, so educators and other folks who got fed up started pushing for copious amounts of comments.
Another author, Eric Jeker, raises some excellent points for the “comment liberally” crowd. First, he argues that mid-level developers likely spout a position similar to mine because they see commenting as a newbie practice. I tend to agree with him here. Tech has a lot of cultural issues, so elitism probably drives the “no comment” position a bit.
Second, he talks a lot about wasting time and how comments can fit into a workflow that saves you time. In particular, I like this passage:
Personally, I like to add comments in my code because it eases my life so much when I get back to some old applications I wrote in the past. I hate it when I fail to comment some code, and I lose time understanding it again, which is why it has become a reflex for me to write comments in the first place.
Sometimes, I even implement what I call CDD (Comment Driven Development), especially when I have to write a complex algorithm. I like to first break it down into small parts, without worrying about the syntax. I write this in my comments and then “translate” those into whatever language I’m currently writing. When I finish, I clean up the useless ones.
Commenting Code: Necessity or Redundancy?
Overall, the argument around liberal commenting seems to be that they do not affect how code runs and can be edited or removed as needed. In other words, they’re not harming anyone: a position that runs contrary to the first position we discussed.
Revising My Personal Commenting Style
In the three categories above, I sort of positioned them as minimal, medium, and maximum. That said, there are probably dozens of different ways folks approach commenting. In fact, after writing this article, I think I want to take some time to revise my position a bit.
First, I still adhere to the idea that fewer comments is better. I don’t agree that comments are entirely harmless for many of the reasons that have been discussed throughout. For example, comments can become outdated or may convey meaningless or cryptic information that wastes more time.
That said, I do like Jason’s intent model that focuses on making good comments. I don’t know that his position entirely differs from mine, but at the very least, he seems to be providing a framework that works to eliminate some of the drawbacks I mentioned above.
If I pick up anything from this, it’ll probably be the language that I use when creating comments. When I first learned to write comments, I wasn’t really told what to write—just that I should write something. Many of the folks I referenced in this article seem to have some decent strategies related to writing comments.
Overall, I will probably shy away from comments less often if it means supporting folks that end up reading my code. At the end of the day, I want to make sure I’m aware of the needs of the people I work with. That’s the compassionate thing to do.
With that said, that’s all I have for today. This is a bit different than what I usually write. If you liked it, I’ll try to make more content like it. If not, no worries! Just make sure you let me know over on Discord or Patreon which you can find here. Otherwise, take care!
Recent Posts
As the semester starts to wrap up, I'm a bit busy and a bit burnt out. As a result, I thought I'd have a little fun writing about nasty little bugs I've run into over time. I'll keep it short; don't...
I find the structure of relational databases to be appealing. They allow you to store data in various tables that eliminate redundancy, reduce storage size, and combine easily. Therefore, it should...