Python Comments

Summary: in this tutorial, we will show you how to add comment into your code. You will learn various kind of Python comments including block comment, inline comment and documentation string.

When the program is getting bigger and more complicated, it is getting difficult to read and maintain. For these reasons, it is a good practice to put some documentations or notes into your code. These notes are called comments.

The code only can tell you how it does but cannot tell you why it does so. However, your comment can do that. You use comments to explain the formulas, complex algorithms and sophisticated business logic.

Python comment begins with a hash or pound (#) sign and continues to the end of the line. It is important to note that Python interpreter ignores comments when it interpret the code.

Python provides three kinds of comments including block comment, inline comment and documentation string.

Python Comments

Python block comments

You use a block comment to explain the code that follows it. A block comment is indented at the same level as the code block. To write a block comment, you start with a single hash (# ) sign followed by a single space and comment.

The following code illustrates how to make a block:

Python inline comments

If a comment is placed on the same line as a statement, it is called an inline comment. Similar to the block comment, an inline comment begins with a single hash (# ) sign and followed by a space and comment.

It is recommended that an inline comment should separate from the statement at least two spaces. The following example demonstrates an inline comment.

Python documentation string or docstrings

A documentation string is a literal string that you put as the first statement in a function, module, class, or method definition. Different from a regular comment, documentation string can be accessed at run-time using  obj.__doc__ attribute where obj is the name of function, module or class, etc.

Documentation string is also used to generate documentation automatically. Documentation string is also known as docstrings.

Python provides two kinds of docstrings: one-line docstrings and multi-line docstrings.

One-line docstrings

One-line docstring fits in one line begins with triple quotes and ends with triple quotes. There should not have a blank line either before or after the one-line docstring.

The following example illustrates one-line docstring in  quicksort() function:

Multi-line docstrings

As its name implies, multi-line docstring can span multiple lines. Just like one-line docstring, the first line of multi-line docstring is a summary, followed by a blank line and of course more descriptions underneath.

The following example shows you how to use multi-line docstrings:

Python multiline comments

Python does not support multiline comments like C/C++ or Java. However there is nothing to stop you to use multi-line docstrings as multiline comments. This is also mentioned by Guido van Rossum, the creator of Python.

It is important to keep you comment clear, concise and explanatory. The ultimate goal is to save time and energy for maintenance developers who will work on the code.

In this tutorial, we have introduced you various kinds of Python comments that helps you document your code to make your code easier to maintain.

  • Was this tutorial helpful ?
  • YesNo