Python for Programmers: Docstrings

• So far, we've seen strings in 'single quotes' and "double quotes". Python also supports triple-quoted strings, like """hello""". These have two benefits. First, they can include both single quote and double quote characters without escaping them like \' and \".

• >

  """we can use both " and '"""

  Result:

  Run Code

• (Python formatted that as a single-quoted string, escaping the ' character as \'. But the \' still represents a single quote character, equivalent to the one in our triple-quoted string.)

• The second benefit is that triple-quoted strings can contain newline characters, which let us write multi-line strings easily. In the next example, the escape code \n in the output indicates a newline character.

• >

  s = """a
  multi-line
  string"""
  s

  Result:

  Run Code

• The examples above show some good uses for triple-quoted strings. But their most common use is in "docstrings", a type of documentation in Python. In Python, we commonly document functions, classes, and modules by putting a string at the top of them.

• There's a good reason for this: putting the documentation inside of a string makes it available at runtime. When the first expression inside of a Python function is a string, that string is available in the function's .__doc__ attribute. (And likewise for classes and modules.)

• >

  import math
  
  def hypotenuse(side1, side2):
    """
    Calculate the length of a triangle's hypotenuse.
    Works with ints or floats.
    """
    return math.sqrt(side1**2 + side2**2)
  
  hypotenuse.__doc__

  Result:

  Run Code

• That triple-quoted string includes every character between the opening """ and the closing """. It includes the newlines and the indentation, which is why the string starts with "\n " and ends with "\n ".

• Docstrings are often long, so they're triple-quoted as shown above. But the .__doc__ attribute also works with single-quoted strings.

• >

  def add(a, b):
    "Add two numbers"
    return a + b
  
  add.__doc__

  Result:

  'Add two numbers'

• Functions that don't include a docstring still have a .__doc__ attribute, but its value is always None.

• >

  def swap_tuple_values(t):
    return (t[1], t[0])
  
  swap_tuple_values.__doc__

  Result:

  None

• Strings only become docstrings when they're the first statement in a function. A string anywhere else in the function has no effect.

• >

  def hypotenuse(side1, side2):
    third_side = math.sqrt(side1**2 + side2**2)
    "Calculate the length of a triangle's hypotenuse"
    return third_side
  
  hypotenuse.__doc__

  Result:

  None

• Docstrings aren't just for our code. Python uses them extensively throughout the language and standard library.

• When we're at a REPL (a Python shell or console), we can call help on any value. That shows us the value's docstring.

• >

  help(len)

  console output

  Run Code

• Internally, that help function accessed the .__doc__ attribute that we saw earlier. We can see the same documentation by accessing the attribute.

• >

  len.__doc__

  Result:

  Run Code

• Docstring conventions and formatting vary heavily from project to project, but there are some common patterns. As a baseline, docstrings say what the function, class, or module does. Sometimes they document individual arguments and the return value. Sometimes they document other important information, like assumptions that the function makes about its inputs or exceptions that it can raise.

• Some teams use automated tools to generate standalone documentation from docstrings, usually as web pages. Other teams use docstrings as another comment syntax, without any additional tools involved.

• Docstrings can't directly prevent bugs, but they can help us to see mistakes before we make them. They're especially helpful when looking at code that we haven't seen before. You might know all of your own code's assumptions, but other developers reading your code won't!