Module 6d: Docstrings

Hide code cell source

 
import sys
import os
sys.path.insert(0, os.path.abspath(os.path.join(os.getcwd(), '..', 'shared')))
import setup_code
stroke_data = setup_code.stroke_data

Module 6d: Docstrings#

Section Objectives:
- Write and utilize docstrings to document functions.

Docstrings#

Let’s go back to the count_stroke_patients() function from the first section of this module. Notice how we had a multi-line string in triple quotes, also called documentation string or docstring for short. The docstring links explanatory documentation to Python objects such as functions, modules, and classes. It explains the purpose of the function, as well as the parameters required,and the output/return we get. It is incredibly useful for others (as well as future you!) to develop this good practice.

You can access an object’s documentation through the __doc__ method or help() function.

stroke_data = setup_code.stroke_data

def count_stroke_patients(df):
    """
    Return the number of patients in the dataset who had a stroke.

    Parameters
    ----------
    df : pandas.DataFrame
        The dataset containing patient information. Must include a 'stroke' column
        with binary values (e.g., 0 = no stroke, 1 = stroke).

    Returns
    -------
    int
        The number of patients who had a stroke.
    """
    stroke_count = df['stroke'].sum()
    return stroke_count

print("Using __doc__:")
print(count_stroke_patients.__doc__)

print("Using help:")
help(count_stroke_patients)

Using __doc__:

Return the number of patients in the dataset who had a stroke.

Parameters
----------
df : pandas.DataFrame
    The dataset containing patient information. Must include a 'stroke' column
    with binary values (e.g., 0 = no stroke, 1 = stroke).

Returns
-------
int
    The number of patients who had a stroke.

Using help:
Help on function count_stroke_patients in module __main__:

count_stroke_patients(df)
    Return the number of patients in the dataset who had a stroke.

    Parameters
    ----------
    df : pandas.DataFrame
        The dataset containing patient information. Must include a 'stroke' column
        with binary values (e.g., 0 = no stroke, 1 = stroke).

    Returns
    -------
    int
        The number of patients who had a stroke.

For the sake of standardization, there a few conventions to follow when writing a docstring, mainly based on PEP 257 [@pep_257] and common community practices [@python_docstrings].

  1. Basic Syntax Rules

  • Use “”“triple double quotes”“” even for one-liners.

  • Place the docstring immediately after the def or class line.

  • For raw strings (e.g., with backslashes), use r”““insert raw docstring here”””.

  • Stick to one format, for example the Numpydoc Style used in the count_stroke_patients() function.

  1. One-line Docstrings

  • Used for simple functions or when a brief summary suffices.

  • Format:

    • Triple quotes on a single line.

    • No blank line after.

    • Imperative mood: “Return…” not “Returns…”

    • End with a period.

    Example:

  1. Multi-line Docstrings

  • Format:

    • First line: summary, fits on one line.

    • Blank line after summary.

    • Optional: detailed description (behavior, arguments, exceptions, return).

    • Closing “”” on its own line if the docstring spans multiple lines.

    Example: see example function in building blocks section.

References#

[Dat22]

DataCamp. Python vs r for data science: which should you learn? https://www.datacamp.com/blog/python-vs-r-for-data-science-whats-the-difference, 2022.

[Jup15]

Project Jupyter. What is a notebook. https://docs.jupyter.org/en/latest/#what-is-a-notebook, 2015.

[Mic25]

Microsoft. Windows subsystem for linux. https://learn.microsoft.com/en-us/windows/wsl/about, 2025.

[Pan25]

Pandas. Pandas.series — pandas documentation. https://pandas.pydata.org/docs/reference/api/pandas.Series.html, 2025. Accessed: 2025-06-25.

[NumPyDevelopers]

NumPy Developers. What is numpy? Accessed: 27-04-2025. URL: https://numpy.org/doc/stable/user/whatisnumpy.html.

[PythonSFoundation25]

Python Software Foundation. Beginner's guide to python. https://wiki.python.org/moin/BeginnersGuide, 2025.

Contents