Comments and Docstrings

by Nigel George

Comments are common to most programming languages and are essential to describing code so you or other programmers can understand what is going on when the code is read in future.

Comments in Python are preceded by a hash (#) and a space:

# This is a comment.

Comments can be inline:

x = y + 1	# This is an inline comment

Or single line:

# Define the list of guitarists 
shredders = ["Kirk", "Dave", "Dimebag"]

Python doesn’t have multi-line comments per se—you create multi-line comments by using multiple single line comments:

# This is the first line of the comment,
# This is the second line.
# You can create multi-paragraph comments by
# separating paragraphs with a line containing a single #

Docstrings are a special kind of string used by the Python compiler to create documentation automatically for your modules, classes, methods and functions.

A docstring is the first statement after the declaration of a module, class, method or function. They have two formats; single line:

"""This is a single line docstring"""

And multi-line:

"""This is a multi-line docstring.

The first line is a summary line, followed by a blank line and then a more 
detailed description - often describing arguments, return values, exceptions 
raised and calling restrictions.

The summary statement can be on the same line as the opening triple quotes 
or on the line below.

The closing triple quotes, however, must be on their own line.

The docstring becomes the __doc__ special attribute for the object which is used by many tools and applications, including Django’s admin documentation tool, to create documentation for your code.

For more information on docstrings, see PEP 257.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}