[Duvida] Porque usar docstring ao invés de apenas comentar

Oi João, tudo bem? 😊

Entendi sua dúvida sobre docstrings e comentários em Python.

Docstrings são strings de documentação usadas para documentar módulos, classes, funções e métodos.

Embora ambos sirvam para explicar o código, docstrings têm vantagens importantes.

Docstrings são acessíveis em tempo de execução através do atributo __doc__.

Isso permite que ferramentas de documentação automática, como Sphinx, extraiam e formatem a documentação do seu código.

Comentários são ignorados por essas ferramentas.

Docstrings são uma prática recomendada porque facilitam a geração de documentação, ajudam na legibilidade do código e são acessíveis programaticamente.

Usar docstrings é uma convenção amplamente aceita na comunidade Python.

def soma(a, b):
    """
    Retorna a soma de dois números.

    :param a: O primeiro número.
    :param b: O segundo número.
    :return: A soma de a e b.
    """
    return a + b

print(soma.__doc__)
# Retorna:
# Retorna a soma de dois números.
#
#    :param a: O primeiro número.
#    :param b: O segundo número.
#    :return: A soma de a e b.

🎓 Para saber mais:

• PEP 257 -- Docstring Conventions.
• Documenting Python Code: A Complete Guide.
• Google Python Style Guide - Docstrings.