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.)