Saturday 11 January 2014 — This 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
#This is less readable
Versus:
# This is more readable because of the space
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. :-)
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.
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".
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.
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.
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.
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.
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.
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?
Add a comment: