What Is Docstring In Python With Example

A docstring in Python is a string literal used to document a module, class, function, or method. It is placed as the first statement within these code blocks and is used to provide information about the purpose, usage, and other relevant details of the code. Docstrings are typically enclosed in triple quotes (either single or double) and can span multiple lines.

Here’s an example of a docstring for a Python function:

def calculate_square_area(side_length):
    """
    Calculate the area of a square.

    This function takes the length of one side of a square as input and
    returns the area of the square.

    Parameters:
    side_length (float or int): The length of one side of the square.

    Returns:
    float: The area of the square.

    Example:
    >>> calculate_square_area(5)
    25.0
    """
    return side_length ** 2
Code language: Python (python)

In this example:

  • The docstring is enclosed in triple double quotes (""").
  • It provides a brief description of the function’s purpose.
  • It documents the parameters that the function accepts (side_length) and their types.
  • It documents the return value of the function (float).
  • It includes an example of how to use the function.

Docstrings are an essential part of Python code because they help developers and users understand how to use the code effectively and can be accessed as documentation through tools like help() or by using docstring extractors to generate external documentation. Properly documented code is more maintainable and accessible to others who might collaborate on the code.

What is the most common Python docstring?


The most common Python docstring style, often referred to as the “Google Style Docstring” or “Google Python Style Docstring,” is widely used in the Python community. It’s not an official standard, but it has become a de facto standard due to its clarity and popularity.

The Google Style Docstring typically consists of the following sections:

  1. Module/Function/Class Description: A brief one-line description of the module, function, or class. This comes immediately after the opening triple quotes.
  2. Parameters: A section that describes the function or method parameters, including their names, types, and a brief explanation of what they represent. Parameters are listed as bullet points. For example:
Args:
    param1 (type): Description of param1.
    param2 (type): Description of param2.
Code language: Python (python)
  1. Returns: A section that describes the return value (if applicable) along with its type and a brief explanation. For example:
Returns:
    return_type: Explanation of the return value.
Code language: Python (python)
  1. Raises: A section that lists the exceptions or errors that the function can raise and their meanings. For example:
Raises:
    ExceptionType: Explanation of when and why this exception is raised.Code language: Python (python)
  1. Examples: One or more examples of how to use the function or class. These examples are often presented using the >>> prompt to indicate code that can be executed interactively. For example:
Examples:
    >>> function_name(arg1, arg2)
    Result of function call.
Code language: Python (python)

Here’s a complete example of a Google Style Docstring for a Python function:

def calculate_rectangle_area(length, width):
    """
    Calculate the area of a rectangle.

    Args:
        length (float or int): The length of the rectangle.
        width (float or int): The width of the rectangle.

    Returns:
        float: The area of the rectangle.

    Examples:
        >>> calculate_rectangle_area(5, 3)
        15.0
    """
    return length * width
Code language: Python (python)

Keep in mind that while the Google Style Docstring is one of the most common docstring styles in Python, there are other styles like reStructuredText (reST) and NumPy docstring styles. The choice of which style to use often depends on the project’s or team’s preferences and any existing conventions in the codebase.

Read More;

  • Muhammad Nabil

    I am a skilled and experienced Python developer with a huge passion for programming and a keen eye for details. I earned a Bachelor's degree in Computer Engineering in 2019 from the Modern Academy for Engineering and Technology. I am passionate about helping programmers write better Python code, and I am confident that I can make a significant contribution to any team. I am also a creative thinker who can come up with new and innovative ways to improve the efficiency and readability of code. My specialization includes Python, Django, SQL, Apache NiFi, Apache Hadoop, AWS, and Linux (CentOS and Ubuntu). Besides my passion for Python, I am a solo traveler who loves Pink Floyd, online video games, and Italian pizza.

    View all posts

Leave a Comment