Docstrings and documentation in Python - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is a docstring in Python?

A docstring is a special string placed at the beginning of a function, class, or module that explains what it does. It helps others understand the code without reading all the details.

beginner

How do you write a docstring for a function?

You write a docstring by placing a string enclosed in triple quotes (""" or ''') right after the function definition line. For example:

def greet():
    """Prints a greeting message."""
    print('Hello!')

beginner

Why is documentation important in programming?

Documentation helps people understand what the code does, how to use it, and why it was written that way. It makes maintaining and sharing code easier and saves time in the long run.

intermediate

What tool can you use to view a function's docstring in Python?

You can use the built-in help() function or access the __doc__ attribute. For example, help(function_name) or print(function_name.__doc__) will show the docstring.

intermediate

What are some common sections included in a detailed docstring?

Common sections include:
- Description: What the function/class/module does
- Parameters: Inputs the function takes
- Returns: What the function gives back
- Examples: How to use it
These help users understand and use the code correctly.

Where should a docstring be placed in a Python function?

A At the end of the function

B Before the function definition line

C Outside the function, in a separate file

D Immediately after the function definition line

A docstring must be placed right after the function definition line, inside the function body.

Which of these is the correct way to write a docstring?

A """This function adds two numbers."""

B // This function adds two numbers

C # This function adds two numbers

D <!-- This function adds two numbers -->

Python docstrings use triple quotes (""" or ''') to enclose the documentation string.

What does the help() function do when used on a Python function?

A Displays the function's docstring and usage information

B Runs the function

C Deletes the function

D Compiles the function

The help() function shows the docstring and other useful information about the function.

Why should you write docstrings in your code?

A To make the code run faster

B To explain what the code does for others and yourself

C To hide the code from others

D To make the code shorter

Docstrings help explain the purpose and usage of code, making it easier to understand and maintain.

Which of these is NOT typically included in a detailed docstring?

A Parameters description

B Return values

C Code implementation details

D Examples of usage

Docstrings focus on what the code does, not how it is implemented internally.

Explain what a docstring is and why it is useful in Python programming.

Think about how you would tell a friend what a function does without showing the code.

Describe the typical structure of a detailed docstring for a function.

Imagine writing instructions for someone to use your function correctly.

Practice

1. What is the main purpose of a docstring in Python?

easy

A. To store variable values

B. To execute code automatically

C. To explain what a function, class, or module does

D. To import external libraries

Solution

1. Step 1: Understand what docstrings are

   Docstrings are special strings placed right after function, class, or module definitions to describe their purpose.

2. Step 2: Identify the purpose of docstrings

   They help explain what the code does, making it easier for others and yourself to understand.

3. Final Answer:

   To explain what a function, class, or module does -> Option C

4. Quick Check:

   Docstrings = Explanation [OK]

Hint: Docstrings describe code purpose inside triple quotes [OK]

Common Mistakes:

• Thinking docstrings run code
• Confusing docstrings with comments
• Using docstrings to store data

2. Which of the following is the correct way to write a docstring for a function in Python?

easy

A. def func():
// This is a docstring

B. def func():
# This is a docstring

C. def func():
"This is a comment"

D. def func():
'''This function does something'''

Solution

1. Step 1: Identify correct docstring syntax

   Docstrings use triple quotes (''' or """) placed immediately after the function header.

2. Step 2: Check each option

   def func(): '''This function does something''' uses triple single quotes right after the function header, which is correct. Options B and C use comments or double quotes incorrectly. def func(): // This is a docstring uses // which is not valid in Python.

3. Final Answer:

   def func(): '''This function does something''' -> Option D

4. Quick Check:

   Triple quotes after function = docstring [OK]

Hint: Docstrings use triple quotes right after function header [OK]

Common Mistakes:

• Using # instead of triple quotes
• Using single or double quotes only
• Placing docstring before function header

3. What will be the output of the following code?

def greet():
    '''Return a greeting message.'''
    return "Hello!"

print(greet.__doc__)

medium

A. Return a greeting message.

B. None

C. Hello!

D. SyntaxError

Solution

1. Step 1: Understand __doc__ attribute

   The __doc__ attribute of a function returns its docstring, which is the string inside triple quotes right after the function header.

2. Step 2: Check the function's docstring

   The function greet has the docstring 'Return a greeting message.'. So, greet.__doc__ will output this string.

3. Final Answer:

   Return a greeting message. -> Option A

4. Quick Check:

   Function.__doc__ = docstring text [OK]

Hint: Use function.__doc__ to get its docstring text [OK]

Common Mistakes:

• Expecting function return value instead of docstring
• Confusing __doc__ with print output
• Assuming __doc__ is None if no docstring

4. Identify the error in the following code snippet:

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

medium

A. Docstring should use single quotes

B. Missing closing triple quotes for the docstring

C. Incorrect indentation of return statement

D. Function missing return statement

Solution

1. Step 1: Check docstring syntax

   The docstring starts with triple double quotes """ but does not have a closing triple quote before the return statement.

2. Step 2: Identify the error caused

   Without closing triple quotes, Python treats the return line as part of the string, causing a syntax error.

3. Final Answer:

   Missing closing triple quotes for the docstring -> Option B

4. Quick Check:

   Docstrings need opening and closing triple quotes [OK]

Hint: Always close triple quotes in docstrings [OK]

Common Mistakes:

• Forgetting to close triple quotes
• Indenting return inside docstring
• Using single quotes inconsistently

5. You want to write a docstring for a function that calculates the area of a rectangle. Which of the following docstrings best follows good documentation practice?

hard

A. """Calculate the area of a rectangle given width and height.

Parameters:
width (float): The width of the rectangle.
height (float): The height of the rectangle.

Returns:
float: The area of the rectangle."""

B. """Calculate area."""

C. """Area function"""

D. """Returns width * height"""

Solution

1. Step 1: Understand good docstring content

   A good docstring clearly explains what the function does, its parameters, and what it returns.

2. Step 2: Compare options

   """Calculate the area of a rectangle given width and height. Parameters: width (float): The width of the rectangle. height (float): The height of the rectangle. Returns: float: The area of the rectangle.""" provides a clear description, lists parameters with types, and explains the return value. Other options are too short or vague.

3. Final Answer:

   """Calculate the area of a rectangle given width and height. Parameters: width (float): The width of the rectangle. height (float): The height of the rectangle. Returns: float: The area of the rectangle.""" -> Option A

4. Quick Check:

   Good docstrings = clear + parameters + return [OK]

Hint: Include purpose, parameters, and return in docstrings [OK]

Common Mistakes:

• Writing too short or vague docstrings
• Not mentioning parameters or return values
• Using incomplete sentences