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)

3. 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)

4. 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)

5. 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;

• Python calling yaml.load() without loader=… is deprecated
• What is the use of #! (shebang) In Python?
• Does Python have floor?
• What is Startswith with options in Python?
• What is the string that starts with U in Python?
• What is kwargs in Python With Example?
• How does Kivy work with Python?
• What Is qt For Python With Examples
• What is a non-blocking code in Python?
• What is the Keras Model in Python With Example?
• What is the difference between Python and py command?
• What is the difference between py and PYW file?