Python tutorials > Core Python Fundamentals > Basics and Syntax > What are docstrings?

What are docstrings?

Docstrings (documentation strings) are multiline strings used to document Python code. They are written within triple quotes ('''Docstring''' or """Docstring""") and are placed immediately after the definition of a function, class, module, or method. Docstrings explain what the code does, its parameters, return values, and any exceptions it might raise. They are an essential part of writing readable and maintainable Python code.

Basic Docstring Example

This example shows a simple function with a docstring. The docstring explains what the function does. Note the use of triple quotes. The triple quotes allow the docstring to span multiple lines. You can access the docstring using the __doc__ attribute.

def greet(name):
    '''
    This function greets the person passed in as a parameter.
    '''
    print(f"Hello, {name}!")

Accessing Docstrings

You can access a docstring using the __doc__ attribute of the function, class, or module. The output will be the string you defined within the triple quotes. Accessing docstrings programmatically allows tools like documentation generators (e.g., Sphinx) to automatically create documentation from your code. The example shows an enhanced docstring that includes Args and Returns sections. While Python doesn't enforce these sections, they are a common convention.

def greet(name):
    '''
    This function greets the person passed in as a parameter.
    
    Args:
        name (str): The name of the person to greet.
    
    Returns:
        None
    '''
    print(f"Hello, {name}!")

print(greet.__doc__)

Docstrings for Classes

Docstrings are also used for classes. The class docstring describes the purpose of the class and its attributes. Method docstrings describe the behavior of individual methods. Good class and method docstrings greatly improve the understandability of object-oriented code. The example shows the class docstring and then the docstring of the bark method.

class Dog:
    '''
    A class representing a dog.
    
    Attributes:
        name (str): The name of the dog.
        breed (str): The breed of the dog.
    '''
    def __init__(self, name, breed):
        self.name = name
        self.breed = breed

    def bark(self):
        '''
        Makes the dog bark.
        '''
        print("Woof!")

print(Dog.__doc__)
print(Dog.bark.__doc__)

Concepts Behind the Snippet

The core concept behind docstrings is providing easily accessible documentation embedded directly within the code. This makes it easier for developers to understand what a piece of code does without having to read the implementation. It leverages Python's dynamic nature to allow introspection of the code's documentation at runtime.

Real-Life Use Case

Consider a large software project with multiple developers. Without proper documentation, understanding the purpose and usage of various functions and classes becomes extremely difficult. Docstrings address this by providing a standardized way to document code, which can then be used to generate API documentation using tools like Sphinx. This API documentation serves as a comprehensive reference for developers using the project's code.

Best Practices

  • Be Concise: Docstrings should be concise and to the point. Avoid unnecessary details.
  • Follow a Standard: Use a consistent docstring style (e.g., Google style, NumPy style, reStructuredText).
  • Document Parameters and Return Values: Clearly document the purpose, type, and possible values of parameters and return values.
  • Document Exceptions: Mention any exceptions the function or method might raise.
  • Update Regularly: Keep docstrings up-to-date with code changes.

Interview Tip

During interviews, demonstrating your understanding of docstrings and their importance in writing maintainable code can significantly impress interviewers. Being able to explain different docstring styles (e.g., Google, NumPy, reStructuredText) shows a deeper understanding of Python best practices. Also, be prepared to explain how docstrings are used by documentation generators.

When to Use Them

Use docstrings for:
  • Functions and methods
  • Classes
  • Modules
  • Packages
Basically, document everything that another developer (including your future self) might need to understand to use your code correctly.

Memory Footprint

Docstrings contribute to the memory footprint of your program because they are stored in memory. However, this footprint is usually negligible compared to the rest of the code. Python's garbage collector will eventually remove docstrings if they are no longer needed. If minimizing memory usage is absolutely critical, you can remove docstrings after the program has been initialized by setting the __doc__ attribute to None. However, this is rarely necessary.

Alternatives

While docstrings are the standard way to document Python code, alternatives include:
  • Comments: Inline comments can be useful for explaining specific parts of the code logic, but they are not a replacement for docstrings.
  • External Documentation: Writing documentation in separate files (e.g., Markdown files) is an option for large projects, but it requires more effort to maintain consistency with the code.
Docstrings are generally preferred because they are directly integrated with the code and can be accessed programmatically.

Pros

  • Accessibility: Docstrings are easily accessible via the __doc__ attribute.
  • Integration with Tools: Documentation generators (e.g., Sphinx) can automatically extract docstrings to create API documentation.
  • Readability: Well-written docstrings improve code readability and maintainability.
  • Standardization: Docstrings provide a standardized way to document Python code.

Cons

  • Maintenance: Docstrings need to be kept up-to-date with code changes, which can be an overhead.
  • Verbosity: Writing detailed docstrings can make the code more verbose.
  • Memory Usage: Docstrings consume memory, although this is usually negligible.

← What are dictionary/set comprehensions? What are function annotations? →

FAQ

  • What is the difference between a docstring and a comment?

    A docstring is a multiline string literal that appears as the first statement in a module, function, class, or method definition. It is used to document the code and is accessible via the __doc__ attribute. A comment is a single-line or multiline explanation of the code that is ignored by the Python interpreter. Comments are typically used to explain the logic of the code or to provide temporary notes. Docstrings are intended for documentation, while comments are for explanations within the code itself.
  • What are some popular docstring styles?

    Some popular docstring styles include:
    • Google Style: Uses sections like Args, Returns, Raises.
    • NumPy Style: Similar to Google Style but with more emphasis on documenting numerical code.
    • reStructuredText: A more general-purpose markup language that can be used for docstrings.
    The choice of style is often a matter of personal preference or project conventions.
  • How can I generate documentation from docstrings?

    You can use tools like Sphinx to automatically generate documentation from docstrings. Sphinx reads the docstrings in your code and creates HTML or PDF documentation. It supports various docstring styles and can be customized to fit your project's needs.