Comment writing is a good programming practice that can help you, other programmers or testers add clarity to the program. The following are the kinds of comments in Python.

Single-Line Python Comment

In general most Python programming language textbooks suggest prepending each line with # (hash)  as  the way to comment out each line  in Python.

1
2
 # Just add a comment like this. This line will not be executed.
print("this line will get executed because it doesn't have a hash symbol")

Multiline Python Comment

When comments extends to more than one line it is called a multi-line comment or a block comment. This is used to describe a set of code that is complicated. For example, notice the following lines of code:

1
2
3
4
5
6
7
# while x > 0:
#     x = x-1;
#     if x == 3:
#         break;
#     print(x)

# print("A looping program that won’t execute.")
Did you know, that the # symbol, in Python, is known as the octothorpe; it was devised by a group of Bell Labs Engineers. Click To Tweet

PEP 8 STYLE GUIDE FOR  BLOCK COMMENTING :

  • PEP 8 Style Guide for Python code defines a block comment as one or more paragraph consisting of complete sentences, each sentence ending with a period. Each paragraph should have two spaces in multi-sentence comments except the final sentence.
  • Block comments are indented to the same level as that code..
  • Paragraphs inside a block comment are separated by a line containing a single #.

Most Python IDEs have short keys for commenting out multiline of codes. Here are some tips.

  • To comment and uncomment blocks of code, try selecting multiple lines of code then press Ctrl + /
  • To select a block of codes to comment in NotePad++ use Ctrl+K.
  • PyCharm on Mac use Command + / to comment/uncomment selected block of code .
  • On Windows, using Ctrl + /  (Except Swedish keyboard layout)
  • In PyDevCtrl+4 to comment selected block, Ctrl+5 to uncomment it.
  • In Eclipe using PyDev, we can select a code block and press ctrl+#.

Triple quotes to create multiline comments :

  • To create multiline comments in Python, triple quotes can also be used.  
  • In general the triple quotes are used for docstrings.  Docstrings are the first statements in a module, function, class or method definition and they become the __doc__special attribute of that object.
  •  The triple-quotes can be used to comment out block comments too.
  • Python coders as a convention recommend triple-quotes for documentation strings and   suggest prepending  # with start of each sentences for block comment.
  •  The triple-quotes can be used in one-line Docstrings or Multiline Docstrings.

Example 1:   One-line Docstring Commenting :

1
2
“ “ “Usage: This function takes two values, (a,b) and returns a list.“ “ “
def function(x, y);

Here the opening quotes and closing quotes are in the same line.

Example 2 : Multi-line Docstring commenting:

1
2
3
4
“””
This is the second line of the docstring
“””
def foo()
The above example is three lines long and has two new line characters. The first and last line are blank.

Example 3: Using triple-quotes for block comments:

1
2
3
4
5
6
7
8
9
10
11
12
“”””
This is a
multi-line comment
“””


‘’’
This is
also a multiline
comment ignored by the
python interpreter
‘’’

In Python, “”” triple-quotes “”” is not ignored by python interpreter. The docstrings within triple-quotes are regular strings in Python that are executable statements and if they are not assigned to a variable, they will be garbage collected as soon as the codes execute. Whereas the comments prepended by # are ignored by interpreter.

The greatest Python tip by Guido Van Russom (the author of Python) is that we can use multiline strings as multiline comments. Unless used as docstrings, they generate, no codes.

Conclusion:

Comments are handy when coders look back at their program to improve the code, easily refactoring to benefit others or themselves saving a lot of time, energy and even money in many cases. Python supports multi-line comments either as docstrings in triple quotes or block comments.

BTW, if you’ve been using Python for a while then here’s 5 things that you didn’t know Python could do.


Leave a Reply

Your email address will not be published. Required fields are marked *