Comments should be sentences

Saturday 11 January 2014This is nearly 11 years old. Be careful.

If you really want to write high-quality polished code, you have to attend to many details. A small one that is often overlooked: comments should be complete sentences. (Throughout, “comment” includes docstrings and any other English you write about your code.) Start comments with a capital, have a subject and a verb, and end them with a period.

There are a few reasons for this. First, your program should be readable. Just as you choose variable names to have meaning so that people can read your code, you should write your comments so that people can read them. Capitals are a clear indication of the start of a sentence, and a period is a clear indication of the end:

# BAD:
# try to read the thing

# BETTER:
# Try to read the thing.

Is that first comment complete? Was there meant to be a qualifying clause? The thing that what? Sure, the second sentence doesn’t explain the thing either, but at least we can see that the author didn’t just wander away in the middle of a thought.

By writing complete sentences you are more likely to include some small helper that will get your meaning across, and people will be better able to grasp what your words mean. Isn’t that why you wrote them?

The second reason to write complete sentences is to focus you on what you are writing. You think about each statement in your program, why aren’t you thinking about the comments? Maybe if you capitalize and punctuate your text, you’ll realize that a few grunted words aren’t really what you want to put there:

# EVEN BETTER:
# Try to read the configuration file, but it's OK if
# it's missing because we don't require a config file.

Some would argue that this comment is too many words, that you shouldn’t explain in that much detail, that the code should be more self-explanatory. That’s great, now you’re thinking about what the comment is doing, and making them better. I’m not suggesting writing longer comments just for bulk, if you can say it in fewer words, do, but make them good words in a complete sentence.

Paying more attention to the comments will help you write better code. I can’t tell you how many times I’ve written what I thought was a perfecty good function or line of code, then gone to write the comment or docstring, and realized a better way to do it, or even just a better name. Explaining yourself to others is a really good way to understand what you are doing. Understanding what you are doing is a really good way to write good code.

Another reason to make your comments complete sentences: it makes it easier to extend them later:

# ORIGINALLY:
# try to read the thing

# THEN SOMEONE ADDS:
# try to read the thing. Don't worry if it
# doesn't exist

The person who adds the second sentence had to add the period to the first, and now it looks really strange that the second sentence is unterminated. If the first sentence had been a real sentence, the second sentence could be added naturally.

Many coders will look at this advice and complain that it is way too nit-picking, that punctuation in comments is irrelevant, that since it’s natural language, it’s readable as it is, we don’t have to worry about trivialities like punctuation they are wrong text needs punctuation to be readable leaving it out just makes it hard to parse the sentences see what i did there?

One last reason for full sentences: the programming variant of the broken windows theory says that if you take care of small things, others are more likely to take care of the bigger things. Polished code is more likely to be maintained well and will set the tone for more polished code in the future.

And isn’t that what we all want? Write complete sentences.

Comments

[gravatar]
I totally agree and I've become fanatical about this style of commentary in my own projects. On the other hand, I'm often contributing to others' code bases, where I'm careful to comment in the style established.
[gravatar]
Yes, good commenting rule. Used it myself in some startups I've worked with.
[gravatar]
I started doing this inadvertently when I decided I'd try to write everything as an actual sentence because my grammar was so poor, and it stuck. I think it's a great idea. Unfortunately, programmers are still discussing whether comments are good or bad, which I think just shows how immature our field is.
[gravatar]
Full sentence commenting is an absolute requirement under my watch. Sometimes developer may moan and groan about it a little, but the moment they have to go back and review 6 month old code, they're always happy they put in the extra effort.
[gravatar]
I'd go one step further and insist on proper spelling as well. If I can't trust you to spell English correctly, how can I be sure you're spelling function names correctly?
[gravatar]
I'd also like to add that there should always be a space between the comment character and the comment itself:

#This is less readable

Versus:

# This is more readable because of the space
[gravatar]
The point of writing complete sentences, to my mind, is that they express a complete thought. (I'd say this is the common thread of your first two reasons.) To then use an understood subject in your sentence ruins most of the clarity you tried to achieve!

It's not so bad in this case ("the program"), but if I had a dollar for every complete English sentence in comments or documentation that had an ambiguous understood subject, I could retire today. :-)
[gravatar]
Thank you for writing this. Bad grammar and unclear intent in comments has been a pet peeve of mine for years.
[gravatar]
I've become a staunch believer in the value of docstrings containing detailed prose describing a module, function, or class, even for "private" components.

Two strawman arguments against such comments are that (1) you can just read the code and (2) comments often become outdated or inconsistent with the code. These arguments lose a lot of their power when you think of the comments as a functional part of the code, a redundant description of what the code does.

Thus good comments and code can be checked against each other for consistency. Even if you can read the code, without a good description of _what it is supposed to be doing_ it is often difficult to distinguish intended from unintended behavior. It is likewise difficult to distinguish incidental from essential behavior. These distinctions are key to effective code maintenance: without them you increase your risk of breaking stuff when you fix bugs, extend, or optimize that code.
[gravatar]
Perhaps you are correct about how to write a comment.
But as I see it, if you need to write a comment, perhaps you need to rewrite your code.
In other words, if you need to write a comment explaining / describing what your code does, you probably didn't write nice, clean readable code.

One point I can relate to, s that when you think of the best comment, you will probably improve your code readability. By changing the code.

I suggest the "Clean Code" book. It explains why comments are "code smell".
[gravatar]
Eyal, you wrote "if you need to write a comment, perhaps you need to rewrite your code." I (and I'd expect most programmers) disagree. Well-written code can make it clear *what* it does, but it can neither tell you why it does it or what it is supposed to do. Well-written comments compliment the code, making it easier to maintain.
[gravatar]
Absolutely.

One can hold the beliefs "comments are bad" and "comments should be complete sentences" simultaneously. Comments have a cost (they tend to become untrue, even if they were true to begin with), so their use should be minimised. Sometimes, though, they're necessary to explain why you're doing something surprising or subtle (potentially something you're unable to see how to do more clearly). In those cases they should be complete sentences, correctly spelled, for all the reasons Ned gives.
[gravatar]
I 100% agree with Ned. I hadn't really thought about it, but polishing your comments a little really makes the comments look nicer, and removes some ambiguity, as he says.

Saying you don't need comments for good code is ridiculous in practice. You may not need to explain *what* you're doing, but you often need to explain why. Why are we trimming the last character? Why are we using this function instead of that one?

Sometimes you even need to explain what the code is doing. This can help if the code is unfixably complex, or even just relatively dense in certain areas. Giving a hint as to what a block of code is doing can help devs wrap their head around code that otherwise might take a significant amount of time to understand. However, if you give them an idea of what it's doing, they can understand it more quickly.

The "comments become out of date" canard is old and tired. If this happens, you need to look at why code reviews aren't catching the code/comment mismatch. You *do* perform code reviews on all checked in code, don't you? If not, maybe it's not the comments that are the problem.

BTW, I've read Clean Code, and I was really disappointed with it. While it has some good ideas, it has some patently bad ones... like discouraging comments.
[gravatar]
One point about spelling - it's almost impossible to grep for misspelled words unless you already know exactly how they're misspelled. That goes for comments/function names/variables/etc.
[gravatar]
Nate wrote: "If this happens, you need to look at why code reviews aren't catching the code/comment mismatch."

BINGO! When you see a code/comment mismatch in a code review, or even just reading the code, it is an opportunity to figure out which one is wrong. Sometimes it's the code.
[gravatar]
Idea: Run the code through something like shocco and see if it makes sense as prose.
[gravatar]
The problem with comments is that it can easily be abused. It just takes one lousy programmer to render all the comments created by others useless.

Comments, in my opinion, should be controlled by the team lead in order to avoid confusion and ensure consistency, or else, they'll do more harm than good.

By the way, for those who don't know, comments have a technical cost in many programming languages.
[gravatar]
All this talk about comments falling out of sync, or being misleading, etc: the same is true of code, or variable names, etc. If you treat comments as part of the program, and you review changes, there's no reason to avoid comments. Sure, they can be overdone, and we've all seen examples of "increment i" comments, which are pointless and should be expunged.

But you can pry my comments from my cold, dead fingers...

@Fadi: I don't know what technical cost you mean, I can't imagine what cost you think they might have.
[gravatar]
As a complete beginner to scripting, my largest hurdle (so far) seems to be speaking of the code I've written, in English. Commenting lines, whether necessary or not, forces me to improve my Code to English vocabulary as well as check my own logic, as it pertains to the script. If I can't explain it in my native language, there's a good chance I don't really know what it's doing or should be doing.

Also, as I view code written by more advanced writers, I often find myself lost. It's relieving to be able to read a comment that sheds light on something I may not immediately understand.

Finally:

After a month or so of getting as deep as this newb currently can with Python, the following quote still resounds with me.

Taken from: Learning Python - 5th Edition - O'Reilly, Chapter 1

"...good programmers know that code is written for the next human being who has to read it in order to maintain or reuse it."

In the future, regardless of my skill level or lack thereof, I'd prefer to be known as a "good programmer". Why wouldn't I?
[gravatar]
In the first example I don't see why it matters. So what if the guy walked away in the middle of a thought, as opposed to not giving enough info.

Add a comment:

Ignore this:
Leave this empty:
Name is required. Either email or web are required. Email won't be displayed and I won't spam you. Your web site won't be indexed by search engines.
Don't put anything here:
Leave this empty:
Comment text is Markdown.