Docstring Requirements

Python docstrings are specially formatted comments that provide built-in documentation of programs. The basic conventions of formatting docstrings are explained in PEP 257. In CS 149, we generally follow recommendations from the Google Python Style Guide.

Minimal example

Every Python file you submit must include a docstring at the top that includes the following lines: (1) a short description, (2) your name, and (3) the date.

"""Exercise 1.1 Hello World.

Author: Katherine Johnson
Version: 08/21/2024
"""

Details to notice

• The first line begins with """ and contains a one-line summary of the file. The summary is on the same line as the """.
• Quoting PEP 257:

  The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

• The Author and Version fields are required.
• The docstring ends with """ on its own line.

Longer example

As the course moves forward, you will write longer programs consisting of multiple files. More details will be needed in the docstring, for example:

"""Module for determining how many cakes are needed for a party.

This program will prompt the use to enter the number of guests, how
many slices are in each cake, and how many slices each guest will eat.
It will then print a nicely formatted report describing how many cakes
will be needed and how many slices will be left over.

Author: Fernando Corbató
Version: 10/30/2024
"""

Details to notice

• The summary line (first line) must be informative. Simply writing "HW5" or "PA2" doesn't help the reader understand the purpose of the file.
• Any additional information about the program should appear after a blank line. (For shorter homework exercises, the single-line description is usually sufficient.)

Functions

Each function must include a docstring that describes the purpose of the function as well as all parameters and the return type.

def calculate_slices_needed(people_coming, slices_per_person):
    """Calculate the total number of cake slices needed for all people.

    Calculates the total number of slices of a cake or loaf of bread
    needed to feed a number of people who all eat the same number of
    slices each.

    Args:
        people_coming (int): The number of people who want to eat a slice of
                             cake or bread.
        slices_per_person (int): The number of slices each person will eat
                                 individually.

    Returns:
        int: The total number of slices needed to feed everyone.
    """
    result = people_coming * slices_per_person
    return result

Details to notice

• Once again, the docstring must begin with a single sentence that describes the overall purpose of the function, with any additional detail separated by a blank line.
• All parameters must be documented under the Args heading. Notice that the expected type of the parameter is indicated in parentheses before the colon.
• A description of the return value, including the type, must be included under the Returns heading.

Gradescope is picky

Your formatting needs to match the requirements exactly, or the submission will fail. The feedback isn't always very helpful in tracking down the issue. Here are a few items to pay attention to:

• A function with no parameters should not have the Args section, and a function with no return statement should not have the Returns section.
• Whitespace matters! In general, trailing whitespace is considered bad style: there should be no extra spaces at the end of a line. Required blank lines should be completely blank, including whitespace.

A note on quality

Tools like flake8 can verify that your docstrings are correctly formatted. But such tools can't tell you if your docstrings are any good. Quoting from the Google Python Style Guide:

Pay attention to punctuation, spelling, and grammar; it is easier to read well-written comments than badly written ones.

Comments should be as readable as narrative text, with proper capitalization and punctuation. In many cases, complete sentences are more readable than sentence fragments. Shorter comments, such as comments at the end of a line of code, can sometimes be less formal, but you should be consistent with your style.

Although it can be frustrating to have a code reviewer point out that you are using a comma when you should be using a semicolon, it is very important that source code maintain a high level of clarity and readability. Proper punctuation, spelling, and grammar help with that goal.