Adding Comments to Code

Published on July 29, 2017 by

The code that you have seen so far, has been pretty easy to understand. But imagine that you write a complicated piece of code or just do something where it is not immediately apparent why. Perhaps it totally made sense to you when you wrote that code, but that might not make case when you look at that same piece of code two years later. Trust me, it happens. It might also be someone else looking at the code such as a colleague. Instead of them scratching their neck, we could be kind enough to leave a comment explaining why we did what we did.

We can do that by adding comments alongside our code. A comment is one or more lines of text that the Python interpreter will not try to execute. Instead, it completely ignores comments, because they are intended for human eyes only. Let’s see an example of how to add a comment to a few lines of code.

# The below code declares a variable and prints out its value. This is a comment, by the way.
age = 28
print(age)  # This is an inline comment.

As you can see in the above example, comments are added by writing a hashtag symbol (#) followed by any text of your choice. Any text that follows the hashtag symbol on the same line is ignored by the Python interpreter. Notice how comments may be added on the same line as code statements, which can be referred to as inline comments.

But what if you want to write more than just a couple of words? We could just do this with multiple comments, but that’s not so pretty.

# These
# are
# all
# comments

Instead, Python — like any other programming language — supports multi-line comments. Rather than writing a bunch of sentences to explain the syntax, a code snippet is worth a thousand words. ;-)

"""
The text that we write in here is all ignored by the Python interpreter.
It may also span as many lines as you wish.
"""

That’s all there is to adding comments in Python. Before moving on, it’s worth mentioning that while it can be a good idea to write comments, you should not overdo it. Stick to writing comments where it is not so obvious what the code does and you want to explain what the code does, or why the code was written in that way. Your code should be as self-explanatory as possible, with the goal of other developers — and the future you — being able to read and understand the code without comments. This involves using descriptive variable names. For instance, if you have some code working with a number of minutes, you might consider naming a variable minutes instead of m, because this improves the readability of the code.

Author avatar
Bo Andersen

About the Author

I am a back-end web developer with a passion for open source technologies. I have been a PHP developer for many years, and also have experience with Java and Spring Framework. I currently work full time as a lead developer. Apart from that, I also spend time on making online courses, so be sure to check those out!

Leave a Reply

Your e-mail address will not be published.