Docstring

Uma docstring em Python é uma string usada para documentar o propósito de um módulo, classe, ou função. Ela é colocada logo após a definição (def, class, ou no início de um módulo) e é delimitada por aspas triplas (""" ou ''').

Docstrings são importantes para tornar o código mais legível e compreensível, explicando a funcionalidade de diferentes partes do programa.

Por que usar docstrings

• Facilita a leitura e manutenção do código.

• Ajuda outros desenvolvedores (ou você mesmo no futuro) a entenderem rapidamente o propósito do código.

• Pode ser usada por ferramentas de documentação como o Sphinx para gerar documentação automaticamente.

Boas práticas ao usar docstrings

1. Use aspas triplas ("""), mesmo que a docstring tenha apenas uma linha.

2. Explique claramente o propósito do código.

3. Inclua descrições de parâmetros e valores retornados para funções e métodos.

4. Use linguagem simples e objetiva.

5. Mantenha a formatação consistente.

6. Para linhas muito longas, quebre em várias linhas.

7. Seja breve, mas informativo.

Alguns exemplos de docstring

"""
Este módulo contém funções úteis para manipular strings e números.
"""
# Código do módulo

def exibir_opcoes():
    ''' Exibe as opções disponíveis no menu principal '''
    print('1. Cadastrar restaurante')
    print('2. Listar restaurantes')
    print('3. Alternar estado do restaurante')
    print('4. Sair\n')

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

    Parâmetros:
    a (int ou float): O primeiro número.
    b (int ou float): O segundo número.

    Retorna:
    int ou float: O resultado da soma de 'a' e 'b'.
    """
    return a + b

class Pessoa:
    """
    Representa uma pessoa com nome e idade.
    """

    def __init__(self, nome, idade):
        """
        Inicializa uma nova instância de Pessoa.

        Parâmetros:
        nome (str): O nome da pessoa.
        idade (int): A idade da pessoa.
        """
        self.nome = nome
        self.idade = idade

    def apresentar(self):
        """
        Retorna uma saudação com o nome e a idade da pessoa.

        Retorna:
        str: Uma saudação no formato "Olá, meu nome é <nome> e tenho <idade> anos."
        """
        return f"Olá, meu nome é {self.nome} e tenho {self.idade} anos."