Comments in Python: How to Make Single Line and Multi-Line Comments

One of the most basic things you’ll learn in the Python language is how to write comments in Python. In programming, comments are sections of a code block that are neither read by the compiler or the interpreter. They’re purely for the programmer. You can consider comments as a type of necessary human-readable documentation.

Comments work more or less the same in every programming language. But if you’re new to programming or new to Python, you need an in-depth understanding of how comments work and how to use them. Today, we’ll look at writing comments in Python, how to add comments, how to create a multiline comment, and what types of comments you should use. 

The purpose of comments in Python

The purpose of comments in Python programs is the same as comments in any other programming language—documentation and debugging:

• Documentation. Comments tell programmers (and yourself) the intent of the code that you’re writing. When you read code later, it may not always be clear what that code is doing. 
• Debugging. Comments can help you remove parts of your code that aren’t working so you can isolate which part of it isn’t working. This makes it easier for you to debug your code.

When using comments for documentation, they should always be included. When using comments for debugging sessions, they should be more or less temporary.

Single line comments in Python

The easiest comment in Python is the single line comment. A single-line comment uses a hash character (#), also known as a pound symbol. The comment starts directly at the symbol:

#A single line comment in Python.

Similarly, you can use this along with other codes:

print(“Hello, world!”) #This prints Hello, world!

You can also comment out code this way:

#round(1.234)

The above Python round() function is not going to actually work. It’s going to print nothing because it’s commented out.

Multi-line comments in Python

Python doesn’t actually have an internal syntax for multi-line comments in the way that people are used to.

In Javascript, for instance, you can comment in two ways:

#single-line

/* multiple lines */

This is great for commenting out large blocks of code because you’re able to comment and uncomment code without having to go line by line. Inline comments are the most common types of comments. 

In Python, you have to comment out each individual line to do multiple lines or block comments:

#Multiple #lines #of #comments

But there is one exception, although it’s a little messy. Python ignores things called “string literals,” which is anything that’s between triple quotes. So, you can write something like this:

“”” Multiple lines of comments. “””

Many developers do this, but you really shouldn’t. It’s not intended behavior, even if it’s used that way. There aren’t significant downsides to using this type of code, but it may not always maintain compatibility with future versions of Python and, therefore, may not be something that a developer wants to lean on.

The best practices for commenting on Python code

Commenting on Python code is done purely for the sake of readability. An interpreter entirely ignores comments within code. Still, there are some general best practices:

• Comment on your code as much as possible. This is good practice for any programmer. Your commenting is like a type of documentation. Other programmers won’t be able to tell what you were doing without thorough comments. You might not even be able to tell either!
• Be specific in your code. Don’t say things like “This does x.” Say things like “Function x does y.” Don’t use words that could be confusing, like “this” or “it.” You want to be as precise as possible.
• Don’t leave code commented without a note. If you remove code, you should also leave a note saying why you removed the code. Mostly, this is done for debugging, but other programmers need to know if you’ve intentionally and permanently sliced out a code block.

The best practices for commenting on Python code are essentially the same best practices as commenting on any other type of code. 

Using comments for debugging

Let’s say you have this code that you want to debug:

if a==b print(“A is the same as B”)

For some reason, this code keeps erroring. You could do this:

#if a==b

Now, you just have the other line of code:

print(“A is the same as B”)

At that point, you’d determine that something is wrong with the line:

if a==b

Can you see what it is? It’s missing a colon. The line should be:

if a==b:

Of course, your syntax editor will probably highlight this for you. But this shows how you use comments for debugging: isolating different code areas until you can tell which area isn’t working.

Syntax highlighting and comments

If desired, you could write Python code in a Notepad. But you don’t want to do that. Most people use an IDE, like Visual Studio, to write Python code. Whether they’re making documentation strings or multiline comments in Python, syntax highlighting makes it easier.

When you write Python code using a notepad program (Notepad++, Vi) or an IDE (NetBeans, Visual Studio), all syntax is highlighted, whether it’s a function or a keyword. Different data structures are different colors.

This is particularly useful when it comes to comments. When commenting on Python code, the comments are highlighted so that you can clearly see that the code isn’t running. And when you have multi-line comments, you’ll often be able to collapse them so you can see your code without large comments in the way.

Comments may seem like something trivial about programming, but using them properly is actually very important, if not essential. Poorly commented code can make a program unmanageable and impossible to expand. One thing that employers often look for when they review code is that the code is clearly commented.
So, if you’re interested in writing the best Python code, you should consider learning more about Python syntax, functions, and commenting. Starting with a few Python projects is a great way to learn.