Documenting Python code is pretty straightforward! It is broken up into two components: comments, and docstrings.
Python docstrings go by a few main formats, here are the resources for each of those!
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!
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
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.
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
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.
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
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.
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