Docstrings for functions and classes

Name:

Date:

Class:

Quick Questions

Shade in the A or B circle for each question.

1. Which line correctly starts a docstring for a function?

A # Return the area of a rectangle.

B """Return the area of a rectangle."""

2. Where must a function's docstring be placed?

A On the first line inside the function body, straight after the def line

B At the very end of the function, after the return statement

3. Which function shows a docstring to the user in the Python shell?

A print(calculate_total.comment)

B help(calculate_total)

4. Which docstring best describes a parameter and the return value?

A """Add tax to price. price: float. Returns the total as a float."""

B """This function is very useful."""

5. Which class definition has a docstring in the correct place?

A class Student: """A student with a name and mark."""

B class Student: name = "" """A student with a name and mark."""

Match the Pairs

Draw a line connecting each item on the left to its match on the right.

Left column		Right column
1"""Return the area of a rectangle."""		ADisplays the docstring of the calculate_area function
2help(calculate_area)		BA docstring: a triple-quoted string on the first line of a function body that says what the function does
3A docstring describes each parameter and the return value so other programmers know what to pass in and what comes back		Cclass Student: """A student with a name and a mark."""
4A class docstring goes on the first line inside the class body and describes what the class represents		DSingle quotes were used for a multi-line docstring, which causes a syntax error. Use triple quotes at the start and end.
5def total(a, b): x = a + b """Add two numbers.""" return x		EThe docstring is not on the first line of the function body, so Python does not treat it as the docstring and help() will not show it. Move it above x = a + b.
6def total(a, b): "Add two numbers. Returns the sum." return a + b		F"""Add GST to a price. price: float, the cost before GST Returns: float, the cost with GST """

Definitions

"""docstring"""

Fill in the Blanks

Complete each line of code by filling in the missing parts.

class Student: """A student record.""" help(_______)

def area(w, h): """Return the area.""" ____(area)

def area(w, h): """Return area. ______ w: the width""" return w * h

_____ Student: """A student record.""" count = 0

def area(w, h): """Find area. _______: the area""" return w * h

Spot the Error

Shade in the letter of the line that contains an error.

Question 1

A def area(w, h):

B """Find rectangle area.

C ""

D return w * h

Question 2

A def greet(name)

B """Print a greeting."""

C print("Hi " + name)

Question 3

A define add(a, b):

B """Return a plus b."""

C return a + b

Question 4

A def square(n):

B # Return n squared.

C return n * n

D print(square(4))

Question 5

A def hello(name):

B """Print a greeting."""

C print("Hi " + name)

D help(hello())

Answer Key

Docstrings for functions and classes

Section A: Quick Questions

B — """Return the area of a rectangle."""

A — On the first line inside the function body, straight after the def line

B — help(calculate_total)

A — """Add tax to price. price: float. Returns the total as a float."""

A — class Student: """A student with a name and mark."""

Section B: Match the Pairs

"""Return the area of a rectangle.""" → A docstring: a triple-quoted string on the first line of a function body that says what the function does

help(calculate_area) → Displays the docstring of the calculate_area function

A docstring describes each parameter and the return value so other programmers know what to pass in and what comes back → """Add GST to a price. price: float, the cost before GST Returns: float, the cost with GST """

A class docstring goes on the first line inside the class body and describes what the class represents → class Student: """A student with a name and a mark."""

def total(a, b): x = a + b """Add two numbers.""" return x → The docstring is not on the first line of the function body, so Python does not treat it as the docstring and help() will not show it. Move it above x = a + b.

def total(a, b): "Add two numbers. Returns the sum." return a + b → Single quotes were used for a multi-line docstring, which causes a syntax error. Use triple quotes at the start and end.

Section C: Definitions

"""docstring""" — A triple-quoted string on the first line of a function or class body. It documents what the code does, its parameters and its return value. help() displays it.

Section D: Fill in the Blanks

class Student:
    """A student record."""
help(Student)

def area(w, h):
    """Return the area."""
help(area)

def area(w, h):
    """Return area. :param w: the width"""
    return w * h

class Student:
    """A student record."""
    count = 0

def area(w, h):
    """Find area. :return: the area"""
    return w * h

Section E: Spot the Error

C — The docstring is closed with only two quotes. A triple-quoted docstring must end with three double quotes: """.

A — The function header is missing its colon. It should be def greet(name): so the docstring can sit in the function body.

A — Python functions start with the keyword def, not define. The header should be def add(a, b):.

B — A # comment is not a docstring, so help() cannot show it. The first line of the body should be a triple-quoted string: """Return n squared."""

D — help() needs the function object, not the result of calling it. hello() would run without its argument and fail. It should be help(hello).