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: