python.md

Python Documentation

Documenting Python code is pretty straightforward! It is broken up into two components: comments, and docstrings.

---

Docstrings

Python docstrings go by a few main formats, here are the resources for each of those!

reStructuredText - PEP 287

reStructuredText (reST for short) is a docstring format that leverages the popular plain-text syntax language known as, well, reST. reST is not exclusively used for Python. This is great, because docstrings written use it gain the ability to be used in the vast ecosystem of reST tools!

• CheatSheet
• Spec

Example (thanks, Trelent):

def mult_nums(nums):
    """
    Multiplies all the numbers in a list of numbers.

    :author: Generated by Trelent
    :param nums: The list of numbers to multiply.
    :type nums: list
    :returns: The product of all the numbers in the list.
    :rtype: int
    """
    result = 1
    for num in nums:
        result *= num
    return result

Google

The Google format is a python docstring format style that is widely used, but which originated as a part of Google's internal Python styling guide. It is extremely human-readable, and emphasizes this over support for automated tooling.

• CheatSheet
• Spec

Example (thanks, Sphinx):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

NumPy Docstring Standard

The NumPy Docstring standard is a documentation format standardized by the popular open source math library, NumPy. It is also extremely human-readable, and emphasizes this over support for automated tooling.

• Spec

Example (thanks, Sphinx):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

---

Comments

Code commenting is super helpful to other developers when used in moderation. Comments should be primarily used to explain the, ahem, intricate components of your code.

The do's and don'ts

---

Python comments are really simple to use! Just prefix your comment with a # character like so:

# <Your comment goes here>

A comment can be on its own line:

def foo(a,b):
    # This is a comment!
    return a+b

A comment can follow a piece of code on the same line:

def foo(a,b):
    return a+b # This is also a comment!

Try not to over-use them, docstrings are meant to explain what a broader snippet of code does, not comments!

Good example:

def foo(a,b):
    """Adds together the numbers a and b"""
    return a+b

Bad example:

def foo(a,b):
    # Start with our variables a and b, and add them together
    c = a+b

    # Great, now return the computed sum as c
    return c

---