Python Comments

Python supports multiple ways to add comments to your code. Why do we need this? Let me tell you a story.

A client requires a script that connects to different network devices using SSH, makes some configuration changes, then saves the configuration. No problem, you start working on it today. You are busy, but the client is waiting for results so you have a deadline. You run into multiple issues but you are able to fix your bugs and the script works. Mission completed! You have more work to do so you move on to your next task.

Six months later, the client asks you to make some changes to your network script. Most of the client’s network devices support APIs now so, besides SSH, they also want to communicate using APIs. No problem, you got this. You look at the code you wrote 6 months ago and you have no clue what some parts of your code do and why you coded like this.

Code is read much more often than it is written. What makes sense to you today, might not mean a thing 6 months later. How do we avoid this? One way is by adding comments. Python is a language that is easy to read, but explaining what and why you do certain things is helpful.

Commenting takes time but is worth your time. Be friendly to your future self (or your colleagues). Let’s see what options we have to add comments to code in Python.

Single Line Comment

You can add a single line comment with the # (hash character). You can add it anywhere in your code. For example, above a variable:

# List of Oses for Cisco routers
cisco_os = ["IOS","IOS-XE","IOS-XR"]

Or after a line:

timeout = 30 # default timeout in seconds for SSH.

It’s also useful to (temporarily) disable a line. This causes Python to interpret the line as a comment, so it ignores the line completely:

Multi Line Comments

What if you want to add a comment that doesn’t fit on a single line? You could do something like this:

# Python example script
# Version 1.0
# This script explains comments.

It can be a pain to add the # at the start of each line. An alternative is triple quotes:

"""
Python example script
Version 1.0
This script explains comments.
"""

Start and end with three quotes. Whatever you put in between is a comment.

Docstring Comments

Python supports documentation strings (docstring). This is a convenient way to associate documentation with modules, functions, etc.  You can add a docstring right below your function (with triple quotes) and use it to explain what the function is about:

The docstring above helps to understand what the function is about, but you can also use this to build documentation. By issuing __doc__ after the function name, Python prints the docstring that is included with the function.

There are tools that auto-generate documentation from docstrings. This can be helpful if you have large projects.

PEP8

Besides comments, there is much more you can do to write code that is easy to read. Two quick examples are:

• Use variable names that describe your data. Don’t use abstract variables like x, y, or z but use descriptive variables like “hostname” or “devices”.
• Use function names that describe what the function is about.

I can highly recommend looking at the Python PEP8 style guide. This guide explains how to write beautiful Python code and includes examples of good and bad code. It might not seem important at this stage, but as you begin writing more code, and your code becomes more complex, you will quickly see the benefit of code that is easy to read and understand.

Conclusion

You have now learned how to make your Python code easier to read with comments:

• Code is read more than it is written so use comments to describe what your code does.
• You can add single-line comments anywhere in your code, even at the end of lines.
• You can create multi-line comments with triple quotes.
• Docstring comments are useful to describe what functions do and can be used to build documentation.
• The Python PEP8 style guide is a great way to learn how to write good-looking Python code.

I hope you enjoyed this lesson. If you have any questions please leave a comment.