Documentation Strings

Comments

In Python, you can make a comment using a # character.

# this is a comment

A comment can be made on its own line or after code:

favorite_numbers = [5, 7, 13]  # I like primes

Everything on the line after the # is ignored by Python. We can use this to document intentions that may not be entirely clear.

Python does not have multi-line comments like C and Java do. There are only single-line comments. To make a comment over multiple lines, you’ll need to start every line with a #.

Documentation Strings

Comments are great, but there’s a more powerful tool we can use to document our code.

There is a convention in Python of putting a string at the top of your function, module, or class for documentation:

def power(x, y):
    """Return x raised to the y-th power."""
    return x ** y

This is called a “docstring”.

Python actually uses docstrings to generate the help text for objects.

Note that we have used a triple-quoted string and we wrote a single sentence, starting our string with an uppercase letter and ending it with a period.

Python Enhancement Proposal (PEP) 257 dictates the preferred way to make docstrings.

PEP 257 states that one-line docstrings should:

• use triple quotes to make it easier to turn them into multi-line docstrings
• not have blank lines before or after them
• be a phrase ending in a period written in the imperative tense (in the form of a command)

PEP 257 also dictates suggestions for multi-line docstrings. This PEP is part of the recommended reading.

Docstring all the things

Let’s document our bank_account module:

"""Utilities and objects for managing bank accounts."""


class BankAccount:

    """Bank account including an account balance."""

    def __init__(self, balance=0):
        """Open an account."""
        self.balance = balance
        print("Account opened.")
        self.print_balance()

    def deposit(self, amount):
        """Increase the account balance."""
        self.balance += amount
        print("${} deposited.".format(amount))
        self.print_balance()

    def withdraw(self, amount):
        """Decrease the account balance."""
        self.balance -= amount
        print("${} withdrawn.".format(amount))
        self.print_balance()

    def transfer(self, other_account, amount):
        """Move money from our account to the given account."""
        self.withdraw(amount)
        other_account.deposit(amount)

    def print_balance(self):
        """Print the current account balance."""
        print("Account balance is ${}.".format(self.balance))

    def __str__(self):
        """Return a human-readable explanation of account."""
        return "Account with balance of ${}".format(self.balance)

    def __repr__(self):
        """Return a developer-readable representation of our account."""
        return "BankAccount(balance={})".format(self.balance)

Docstrings can be used on functions, classes, and modules. They must be the first string in each of these.

The use of docstrings

Docstrings are not multi-line comments. These strings should only be used at the beginning of functions, classes, and modules.

Docstrings are used to generate the documentation text shown when we use the help function an object:

>>> import bank_account
>>> help(bank_account)

When parsing our code, Python stores docstrings in a __doc__ attribute on our objects:

>>> bank_account.__doc__
'Utilities and objects for managing bank accounts.'
>>> bank_account.BankAccount.__doc__
'Bank account including an account balance.'

There are a number of tools which can understand and use Python docstrings. `Sphinx`_, the tool used for creating this website, is one of those tools. Sphinx is used for creating documentation and it can generate documentation for Python code based on docstrings.