Welcome back to a new article in my Intro to Programming series. In this quick blog post we will learn how to include code comments in our programs.
What are code comments
So what are code comments? Code comments are pieces of text that are meant to be read only by humans. They exist in order to offer clarifications, talk about trade-offs, serve as reminders or warnings, or mention possible improvements that can be done to the code. Code comments are spread throughout a program and are typically ignored by a computer. Essentially, code comments are a way for you, the code author, to communicate with other humans who might read or change your code in the future (including your future self).
How to create code comments in Python
In Python, code comments are marked using the # symbol. For example:
# This is a comment.
Note how Jupyter notebook knows that this is a comment, so it formats it differently than regular code (it's in italics and green). This line of code will be skipped by the Python Interpreter - and that's a good thing because it really would not know what to do with it.
Code comments can spread across multiple lines. Simply put a # at the beginning of each line containing a code comment:
# This is a multi-line comment.
# A multi-line comment is simply a
# comment that spreads over multiple
NOTE: Generally, you should wrap your comments so that the lines are not too long. This makes comments easier to read.
In Python, everything that comes after a # is considered a comment and the Python Interpreter ignores it. This means that you can include comments on the same line as actual Python code:
euro = 202 # this is an inline comment
When the Python Interpreter reads this line of code, it will define a variable called euro and it will assign to it the value 202. It will then ignore the rest of the line (everything that comes after the #), since that's a comment.
Compare the code above with the following lines of code:
# euro = 205
In line 4, we have the following code: # euro = 205. This whole line is a code comment because, as mentioned above, the Python Interpreter treats everything that comes after a # as a comment, even if it is actual valid Python code.
Because line 4 is commented out, that code never executes, so we can see in line 5 that if we inspect the value stored in our euro variable, it's still 202, not 205.
NOTE: Different programming languages have different ways of creating comments, however pretty much all programming languages allow comments.
Good code comments
Code comments are as important as the code itself, if not more so. Computer code is a living thing: it constantly evolves and changes. Those changes are performed by programmers. Programmers benefit tremendously from clear, concise code, but they also benefit from clear, insightful comments.
You will definitely, at some point in your life as a programmer, hear the phrase: "good code is self-documenting". This means that good code is clear, has a good structure, makes use of properly named variables, functions, classes, etc. and is therefore easy to understand and follow without the need for lengthy documentation. This all is true.
However, some people have taken this to an extreme and claim that since their code is good, it is self-documenting and therefore does not need comments. This way of looking at thing is generally wrong. All programs that are non trivial include at least some lines of code that would benefit from a clarification, a reminder, or some other comments.
Here are some situations where you should use code comments:
- when you need to explain the general workings of a more complex piece of code. However, don't over-explain. Only include comments for those lines of code that are not obvious or that really do need some extra clarification.
- when you need to include a reminder or a warning
- when you need to explain trade-offs
So, in summary, you should use code comments sparingly and they should be clear and to the point. Remember, there is a cost to including code comments: in the best case scenario, they can slow down both the writing and the reading of code.
In the worst case scenario, code comments can become outdated and incorrect, confusing the programmer who is trying to understand your code. However, when they are truly needed, good code comments are crucial.
TIP: Always ask yourself: how will this code comment age? Will it be useful to someone? Will it remain accurate, provided that the code next to it does not change?
Bad code comments
Bad code comments range from unnecessary, to inaccurate, to downright mean.
Unnecessary code comments
An example of an unnecessary code comment is the one below:
# below we set favorite_number to be 17
favorite_number = 17
Why is this unnecessary? Because the code comment doesn't add anything that cannot be understood by just reading the code. It is quite obvious that the code assigns 17 to the variable favorite_number.
NOTE: When you write code comments, you should make the assumption that everyone who reads your code is familiar with the programming language you are using. Therefore, explaining what favorite_number = 17 does is unnecessary.
Inaccurate code comments
The example above, while unnecessary, is not harmful. However, there are situations where code comments can be downright misleading and confusing. For example: code comments that reference specific line numbers in your program.
Why is this an example of a possibly misleading code comment? Because as the program evolves, code lines will be added and/or removed and it's possible that, for example, line 31 in your program will contain completely different code than the code that was there when you wrote your comment.
NOTE: Never mention line numbers in your code comments! Programs are living things - they change and evolve and those line numbers will soon point to different lines of code.
Of course, in this category, we must also include comments that are just plain wrong. For example, consider a code comment explaining that a certain piece of code works a certain way, when in fact, it works in a very different way.
Such comments are particularly confusing for someone reading the code because they present a conundrum: should you believe the comment, and rewrite that piece of code in order to match the comment or should you believe the code and modify the comment?
Mean code comments
This should be pretty obvious. It serves no good to be mean in your code comments. Comments like "this code sucks" or "so-and-so is an idiot and this is why we must create this hack" etc. are not useful and create a bad environment to work in.
In fact, I would also go as far as saying that generally you should probably never include other people's names (or your own) in your code comments.
Before you ask why would you ever do that, consider that most software is written by teams, not by individuals. When in a team, it can be tempting to mention your teammates by name. But remember, code contributors can change. If someone is new to the code base and encounters a code comment about Tim - and Tim has not been with the company for more than 3 years now - how is this comment useful? Who is Tim?
As for the mean part, just don't do it. There are plenty of mean people everywhere as it is, no need to add meanness to software too. It only serves to make the world a worse place.
Before I end this blog post, I want to bring your attention to one more thing: just as code changes and evolves, so do comments. Keep this in mind. If you modify some code, make sure you modify the comments too, such that they still accurately describe the code. Outdated comments are a major source of confusion.
Thanks for reading!