What is a Docstring?
A docstring, or documentation string, is a string literal that occurs as the first statement in a module, function, class, or method definition. It is used to document the purpose and usage of the code component in which it is defined.
Why Use Docstrings?
- Readability: Docstrings make your code easier to understand for others (and yourself) when you revisit it later.
- Documentation: They serve as a built-in documentation tool, providing a standardized way to describe your code.
- Tools Integration: Many tools and libraries (like Sphinx) use docstrings to generate documentation automatically.
Writing Docstrings
Docstrings are written using triple quotes (""" or '''). They can span multiple lines, which is useful for providing detailed explanations.
Example: Module Docstring
A module docstring appears at the top of the Python file and describes the module’s contents.
"""
This module provides basic arithmetic operations.
Functions:
add(a, b) -> int: Returns the sum of two numbers.
subtract(a, b) -> int: Returns the difference of two numbers.
"""
Example: Function Docstring
A function docstring explains what the function does, its parameters, and its return value.
def add(a, b):
"""
Returns the sum of two numbers.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of a and b.
"""
return a + b
Example: Class Docstring
A class docstring describes the class and its methods.
class Calculator:
"""
A simple calculator class.
Methods:
add(a, b) -> int: Returns the sum of two numbers.
subtract(a, b) -> int: Returns the difference of two numbers.
"""
def add(self, a, b):
"""
Returns the sum of two numbers.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of a and b.
"""
return a + b
def subtract(self, a, b):
"""
Returns the difference of two numbers.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The difference of a and b.
"""
return a - b
Docstring Conventions
Follow these conventions to write effective docstrings:
- Begin with a summary line: Start with a short description of the function, class, or module’s purpose.
- Include a blank line: After the summary, include a blank line before adding more details.
- Describe parameters and return values: For functions and methods, describe each parameter and the return value.
- Use consistent style: Stick to one style guide, such as PEP 257, to maintain consistency.
Accessing Docstrings
You can access a function, class, or module’s docstring using the __doc__ attribute or the help() function.
print(add.__doc__)
help(Calculator)
