Commenting in Python (original) (raw)

Don't have an account yet? Sign up here.

Let's talk about commenting Python code.

We have a Python program that prints out Hello!, pauses for a second, and then prints Goodbye! on the same line:

`from time import sleep

print("Hello!", end="", flush=True) sleep(1)

ANSI code to clear current line

print("\r\033[K", end="")

print("Goodbye!") `

It prints Hello!:

~ $ python3 hello.py Hello!

And then one second later it overwrites Hello! with Goodbye!:

~ $ python3 hello.py Goodbye!

It does this using an ANSI escape code (that \033[K string).

The line above the print call in our code is called a comment:

# ANSI code to clear current line print("\r\033[K", end="")

Python's comments all start with the # character.

I call this character an octothorpe, though it goes by many names. Some of the more common names for # are hashmark, number sign, and pound sign.

You can write a comment in Python by putting an octothorpe character (#) at the beginning of a line, and then writing your comment. The comment stops at the end of the line, meaning the next line is code... unless you write another octothorpe character!

Here we've written more details and added an additional line to note that this code doesn't yet work on Windows:

`# ANSI code to clear current line: \r moves to beginning, \033[K erases to end.

Note: This will not work on Windows without code to enable ANSI escape codes.

print("\r\033[K", end="") `

This is sometimes called a block comment because it's a way to write a block of text that represents a comment.

Unlike some programming languages, Python has no multiline comment syntax. If you think you've seen a multiline comment, it may have been a docstring or a multiline string. More on that in multiline comments in Python.

Comments don't need to be written entirely on their own line. You can also write a comment at the end of a line:

print("\r\033[K", end="") # Clear the current line (via ANSI escape code)

This is called an inline comment.

Inline comments can appear after any line of Python code. They can even appear in the middle of a multiline Python expression.

For example, here's a function that contains a fairly complex Python expression:

def is_leap_year(year): return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)

Here's the same expression, split up over multiple lines, with inline comments at the end of certain lines to explain their purpose:

def is_leap_year(year): return ( year % 4 == 0 # Year is a multiple of 4 and ( year % 100 != 0 # But not a multiple of 100 or year % 400 == 0 # Unless it's a multiple of 400 ) )

Note that this is all one Python expression that we've broken up over multiple lines (see implicit line continuation for more on breaking up long lines of code in Python). We've stuck inline comments at the end of specific lines to explain just that line.

It's a common practice for comments to start with a space character so the comment text will be visually separated from the octothorpe character:

So instead of this:

#ANSI code to clear current line

It's more common to write this:

# ANSI code to clear current line

We've put a space after that octothorpe character and before the comment text.

It's also common for inline comments to be separated from the last code character by two or more space characters.

So instead of starting an inline comment right after the last code character, we'd put two spaces between the code and the start of the comment:

print("\r\033[K", end="") # Clear the current line (via ANSI escape code)

The Python Style Guide (PEP 8) talks more about good commenting practices.

When you're just getting started with Python, I recommend leaving comments for yourself everywhere. But eventually, you should try to reduce the need to comment by relying on other techniques to improve your code's readability.

Helpful comments are great, but they're not the answer to every code readability issue. As you dive deeper into Python, well-named variables, short functions, and documentation strings will be even more important than comments.