Docstrings and documentation in Python - Mini Project: Build & Apply

Docstrings and Documentation

📖 Scenario: You are creating a small program to help a friend understand how to write clear explanations inside their Python code. This will make the code easier to read and use later.

🎯 Goal: Build a simple Python function with a proper docstring that explains what the function does, its inputs, and its output.

📋 What You'll Learn

Create a function named add_numbers that takes two numbers as input

Write a docstring inside the add_numbers function explaining its purpose, parameters, and return value

Call the add_numbers function with two numbers

Print the result of the function call

💡 Why This Matters

🌍 Real World

Writing clear docstrings helps other programmers understand your code quickly, just like clear instructions help someone use a tool properly.

💼 Career

Good documentation is a key skill for software developers, making code easier to maintain and collaborate on in teams.

1

Create the function add_numbers

Write a function named add_numbers that takes two parameters called a and b. Inside the function, return the sum of a and b.

Python

# Define the function add_numbers with parameters a and b
# Your code here

Hint

Use the def keyword to create the function and return to send back the sum.

2

Add a docstring to add_numbers

Inside the add_numbers function, add a docstring that explains:
1. The function adds two numbers.
2. The parameters a and b are numbers.
3. The function returns their sum.
Use triple double quotes """ for the docstring.

Python

def add_numbers(a, b):
    """Add two numbers a and b and return the result."""
    # Your code here

Hint

Place the docstring right after the function header, before the return statement.

3

Call the add_numbers function

Call the add_numbers function with the numbers 5 and 7. Store the result in a variable called result.

Python

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

# Call add_numbers with 5 and 7 and save to result
# Your code here

Hint

Use the function name with parentheses and pass the numbers inside.

4

Print the result

Print the value stored in the variable result.

Python

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

result = add_numbers(5, 7)

# Print the result
# Your code here

Hint

Use print(result) to show the output.

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