Comments and Docstrings
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"""
"""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.