CS 149 Docstring Requirements

Python docstrings are specially formatted comments that provide built-in documentation of Python programs. The basic conventions of formatting docstrings were introduced in PEP 257. Unfortunately, there is no universally accepted standard for exactly what information should appear in docstrings or how they should be formatted. For CS 149, we will generally follow the recommendations of the Google Python Style Guide.

See below for examples of properly formatted docstrings.

Modules

Each Python file must include a docstring that describes the overall purpose of the program or module.

"""Program 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: Jane Doe
Version: 2/8/2022

Honor Code and Acknowledgments: 
    This work complies with the JMU Honor Code.
    - I received help debugging the calc_slices method from TA Chris. 
    - John Doe gave me the idea of using the % operator for determining 
      the leftover number of slices.
    - I used this stack overflow answer as an example of how to solve a
      problem of this sort: https://stackoverflow.com/q/19798480
"""

Items to note:

• The first line contains a concise description of the purpose of this file. 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 summary line must be informative. “HW1” or “PA2” doesn’t help the reader understand the purpose of the code.
• Any additional information about the program should appear after a blank line. (For short homework exercises, the single line description will generally be sufficient.)

• The Author, Version and Honor Code and Acknowledgments fields are required. The Honor Code and Acknowledgments field must include the statement “This work complies with the JMU Honor Code” as well as information about any outside help or resources that were used in developing your code. You don’t need to explicitly acknowledge information from our textbook, lecture, or discussion with your instructor.

A note on using outside resources in developing your code: We expect you to use the internet as a resource when solving problems for this course. That doesn’t mean you should be scouring the internet for solutions to your coding exercises. Basically, if you are using the internet to learn how Python works, that’s great! If you are copying and pasting large swaths of code from the internet, you are probably missing the point of the exercise and almost certainly violating the Honor Code.

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

Items to note:

• 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 Returnsheading.

Local Validation

Our Thonny installation instructions explained how to install the flake8 tool for checking the formatting of Python code. The same tool can be used to check if your docstrings are formatted correctly. In order to check docstrings, you’ll need to install two additional packages through the “Manage packages…” tool in Thonny:

• flake8-docstrings
• darglint

You will also need to store a copy of our flake8 configuration file in the same directory as the code you are checking:

• setup.cfg

Once you have completed these steps, you should be able to check for formatting issues by executing flake8 in the Thonny shell:

A note on quality

Tools like flake8 can verify that your docstrings are correctly formatted. They can’t tell you if they 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.