Docstrings for functions and classes

Name:

Date:

Class:

Quick Questions

Shade in the A or B circle for each question.

1. Which line is a correct way to start a function docstring in Python?

A "Return the area of a rectangle."

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

2. Where must a function docstring be placed?

A On the first line inside the function, directly under def

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

3. What does a function docstring typically describe?

A Only the colour of the program's interface

B Its purpose, parameters and return value

4. Which is a class docstring?

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

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

5. Which statement about docstrings is true?

A A docstring is a form of internal documentation inside the code

B A docstring is a separate user manual stored outside the code

Match the Pairs

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

Left column		Right column
1def area(w, h): """Return the area of a rectangle."""		AThe docstring uses single double quotes instead of triple quotes. Docstrings should use triple quotes, as in """text""".
2class Student: """A student with a name and a mark."""		Bdef add(a, b): """Add two numbers. a, b: numbers to add Returns: their sum"""
3A function docstring can list the parameters and the return value so other programmers know how to use it		Cclass Dog: """A pet dog with a name and age."""
4A docstring is written with triple quotes as the first statement inside the function or class body		DThe docstring is not the first statement in the function. It must come straight after the def line, before any other code.
5def area(w, h): x = w * h """Return the area.""" return x		EA class docstring: a triple-quoted string on the first line inside the class that describes what the class represents
6class Car: "A car with a make and a speed." def __init__(self, make):		FA function docstring: a triple-quoted string on the first line inside the function that describes what it does and returns

Definitions

"""docstring"""

Fill in the Blanks

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

___ area(w, h): """Return the area of a rectangle.""" return w * h

_____ Player: """A player in the game.""" lives = 3

def area(w, h): """Return the area of a rectangle.""" ______ w * h

class Dog: """A pet dog with a name.""" def bark(____):

def area(w, h): """Return the area of a rectangle.""" print(area._______)

Spot the Error

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

Question 1

A def add(a, b):

B """Add two numbers.

C Returns the sum.""

D return a + b

Question 2

A def greet(name):

B "Greet a person by name."

C print("Hello " + name)

Question 3

A def square(n)

B """Return n squared."""

C return n * n

Question 4

A def area(w, h):

B """Return the area."""

C return w + h

Question 5

A class Pet:

B # A pet with a name.

C def __init__(self, name):

D self.name = name

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, directly under def

B — Its purpose, parameters and return value

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

A — A docstring is a form of internal documentation inside the code

Section B: Match the Pairs

def area(w, h): """Return the area of a rectangle.""" → A function docstring: a triple-quoted string on the first line inside the function that describes what it does and returns

class Student: """A student with a name and a mark.""" → A class docstring: a triple-quoted string on the first line inside the class that describes what the class represents

A function docstring can list the parameters and the return value so other programmers know how to use it → def add(a, b): """Add two numbers. a, b: numbers to add Returns: their sum"""

A docstring is written with triple quotes as the first statement inside the function or class body → class Dog: """A pet dog with a name and age."""

def area(w, h): x = w * h """Return the area.""" return x → The docstring is not the first statement in the function. It must come straight after the def line, before any other code.

class Car: "A car with a make and a speed." def __init__(self, make): → The docstring uses single double quotes instead of triple quotes. Docstrings should use triple quotes, as in """text""".

Section C: Definitions

"""docstring""" — A triple-quoted string placed first in a function or class that describes its purpose, parameters and return value. It is internal documentation.

Section D: Fill in the Blanks

def area(w, h):
    """Return the area of a rectangle."""
    return w * h

class Player:
    """A player in the game."""
    lives = 3

def area(w, h):
    """Return the area of a rectangle."""
    return w * h

class Dog:
    """A pet dog with a name."""
    def bark(self):

def area(w, h):
    """Return the area of a rectangle."""
print(area.__doc__)

Section E: Spot the Error

C — A multi-line docstring must end with three double quotes. Ending with only two leaves the string unterminated, so it should be Returns the sum.""".

B — A docstring uses triple quotes. A single-quoted string is not a docstring, so it should be """Greet a person by name.""".

A — The function header is missing its colon. It should be def square(n): so the docstring can sit inside the function.

C — The docstring says the function returns the area, but the code adds the sides. It should be return w * h so the code matches its documentation.

B — A class docstring must be a triple-quoted string, not a # comment. It should be """A pet with a name.""".