Welcome back to a new article in my Intro to Programming series. In this quick blog post, you will learn how to include code comments in your programs.

• Intro to Programming: Why Beginners Should Start With Python
• What are Variables In Python and How to Name Them

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 Write and Run Code In Jupyter Notebooks
• Intro to Programming: How to Get Programming Help When You're Stuck

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. 

Jupyter notebooks also allows you to write Markdown to increase the readability of a text document. You can find out more about markdown and how to use it in our article.

• Quick Guide: How to Write Markdown in Jupyter Notebooks.

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
# lines.

• 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

euro

202

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.

What Are 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 things 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.

• Intro to Programming: How to Write and Run 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?

What Are Bad Code Comments?

Bad code comments range from unnecessary, to inaccurate, to downright mean.

Why Avoid 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.

Why Avoid 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, you 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?

Why Avoid 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!

• Read next in the series: Intro to Programming: What are Strings in Python?>