Aprenda Importance of Documentation | Sustaining Code Quality

Why Documentation Matters

Documentation is a cornerstone of sustainable code quality. Clear documentation helps you, your teammates, and future developers:

Understand what your code does;
Learn how to use and interact with your code;
Maintain or extend code effectively;
Avoid confusion and reduce errors over time.

Without clear documentation, even well-structured code can become confusing and error-prone.

Docstrings in Python

In Python, the main way to document your code is with docstrings. A docstring is a special string literal that describes a module, class, function, or method. Docstrings should always:

Explain the purpose of the code;
Describe its parameters and their types;
Specify the return value;
Outline any side effects or exceptions.

This information helps others use your code correctly and allows you to revisit your own work confidently after some time.

Writing Effective Docstrings

To write clear docstrings:

Follow a consistent format;
Focus on clarity and completeness;
For functions, state:
- What the function does;
- What arguments it takes (and their types);
- What it returns;
- Any exceptions it might raise;
For classes, describe:
- The class purpose;
- Details about its attributes and methods.

Python’s conventions, such as those described in PEP 257, recommend using triple quotes for docstrings and placing them immediately after the function or class definition.


              1234567891011121314151617
            
def calculate_area(width: float, height: float) -> float:
    """
    Calculate the area of a rectangle.

    Args:
        width (float): The width of the rectangle.
        height (float): The height of the rectangle.

    Returns:
        float: The area of the rectangle.

    Raises:
        ValueError: If width or height is negative.
    """
    if width < 0 or height < 0:
        raise ValueError("Width and height must be non-negative.")
    return width * height

This function uses a docstring to clearly explain its purpose, parameters, return value, and possible exception. Such documentation makes the function easy to understand and use, even for someone unfamiliar with the code. Comprehensive docstrings also allow tools to automatically generate user-friendly documentation, further improving code accessibility.

1. What is the main purpose of a docstring?

2. Which elements should be included in a good docstring?

Tudo estava claro?

Obrigado pelo seu feedback!

Seção 4. Capítulo 1

Pergunte à IA

Pergunte o que quiser ou experimente uma das perguntas sugeridas para iniciar nosso bate-papo

Suggested prompts:

Can you show me more examples of good docstrings?

What are some common mistakes to avoid when writing docstrings?

How do I use tools to generate documentation from docstrings?

Awesome!

Completion rate improved to 5.26

Deslize para mostrar o menu