O que são Docstrings em Python

Quando começamos a estudar programação, logo entendemos a importância de escrever um código claro e bem organizado. Nesse sentido, uma ferramenta do Python que faz toda a diferença nesse processo são as Docstrings. Elas nos ajudam a criar códigos mais compreensíveis e fáceis de manter. Neste guia, vamos descobrir juntos o que são Docstrings em Python, por que elas são tão úteis e como usá-las na prática. Vamos lá!

O que são Docstrings em Python?

Docstrings, ou “document strings”, são como etiquetas que colocamos no código Python para descrever o que uma função, classe ou módulo faz. Dessa maneira, elas ajudam a identificar claramente a finalidade e o funcionamento de cada parte, como aquelas caixas organizadas que indicam exatamente o que está dentro. Com isso, fica muito mais fácil para outros desenvolvedores (ou até para nós mesmos no futuro) entenderem rapidamente o que cada trecho de código faz e como utilizá-lo.

Definição simples de Docstrings

Uma Docstring é uma string que aparece logo após a definição de uma função, classe ou módulo. Ela é delimitada por três aspas duplas (“”” “””) ou três aspas simples (”’ ”). Por exemplo:

def soma(a, b):
    """Esta função retorna a soma de dois números."""
    return a + b

Neste exemplo, a Docstring explica claramente o que a função soma faz. Isso é extremamente útil, especialmente em projetos maiores, onde o código pode se tornar complexo.

Como as Docstrings se diferenciam de comentários

Embora utilizemos tanto Docstrings quanto comentários para documentar o código, cada um possui um propósito diferente. Usamos comentários para explicar partes específicas do código, sendo ignorados pelo interpretador Python. Já as Docstrings, por serem acessíveis em tempo de execução, podem ser aproveitadas por ferramentas como o Sphinx para gerar automaticamente a documentação do projeto.

Por que as Docstrings são importantes?

A documentação é uma parte essencial do desenvolvimento de software. Sem uma boa documentação, o código pode se tornar difícil de entender e manter. As Docstrings desempenham um papel crucial nesse aspecto.

A documentação desempenha um papel fundamental em esclarecer a intenção do código. Quando nós ou outros desenvolvedores voltamos ao código meses ou até anos depois, as Docstrings servem como um lembrete sobre o que cada parte faz. Além disso, isso se torna ainda mais relevante em equipes, onde diferentes pessoas podem estar trabalhando no mesmo projeto.

Como as Docstrings ajudam na manutenção do código

Manter um código pode ser uma tarefa desafiadora, especialmente quando não nos lembramos do que cada função ou classe faz. As Docstrings ajudam a minimizar esse problema, oferecendo uma descrição clara e concisa de cada parte do código. Isso facilita a identificação de problemas e a implementação de melhorias.

Como criar uma Docstring em Python?

Criar uma Docstring em Python é simples e direto. Vamos ver a sintaxe básica e alguns exemplos.

Sintaxe básica para criar uma Docstring

Para criarmos uma Docstring, devemos colocá-la logo após a definição de uma função, classe ou módulo, utilizando três aspas duplas ou simples. Veja o exemplo:

def multiplicar(x, y):
    """Multiplica dois números e retorna o resultado."""
    return x * y

Neste exemplo, a Docstring explica que a função multiplicar realiza a multiplicação de dois números.

Exemplos de Docstrings em funções

Aqui estão mais alguns exemplos de Docstrings em funções:

def dividir(x, y):
    """Retorna a divisão de x por y.

    Args:
        x (float): O numerador.
        y (float): O denominador.

    Returns:
        float: O resultado da divisão.
    """
    return x / y

Neste exemplo, a Docstring é mais detalhada, explicando os argumentos da função e o que ela retorna. Isso é especialmente útil para funções que têm múltiplos parâmetros ou que realizam operações complexas.

Tipos de Docstrings

As Docstrings podem ser usadas em diferentes contextos, como funções, classes e módulos. Vamos explorar cada um deles.

Docstrings para funções

As Docstrings para funções geralmente descrevem o que a função faz, os parâmetros que ela aceita e o que ela retorna. Isso nos ajuda a entender rapidamente como usar a função.

Docstrings para classes

As Docstrings para classes devem descrever o propósito da classe e, se necessário, os métodos que ela contém. Veja um exemplo:

class Carro:
    """Representa um carro.

    Atributos:
        modelo (str): O modelo do carro.
        ano (int): O ano de fabricação do carro.
    """

    def __init__(self, modelo, ano):
        self.modelo = modelo
        self.ano = ano

Docstrings para módulos

As Docstrings para módulos devem descrever o que o módulo faz como um todo. Elas são colocadas no início do arquivo Python. Por exemplo:

"""Este módulo contém funções para manipulação de strings."""

Como acessar Docstrings em Python?

Uma das grandes vantagens das Docstrings é que podemos acessá-las facilmente em tempo de execução.

Usando a função help()

A função help() pode ser usada para acessar a Docstring de qualquer função, classe ou módulo. Por exemplo:

help(soma)

Isso exibirá a Docstring da função soma, facilitando a compreensão rápida de sua funcionalidade.

Usando a função doc

Outra maneira de acessar a Docstring é usando o atributo __doc__. Por exemplo:

print(soma.__doc__)

Isso imprimirá a Docstring da função soma no console.

Exemplos práticos de uso de Docstrings

Vamos ver alguns exemplos práticos de como usar Docstrings em funções e classes.

Exemplo de uma função com Docstring

def calcular_area(base, altura):
    """Calcula a área de um triângulo.

    Args:
        base (float): A base do triângulo.
        altura (float): A altura do triângulo.

    Returns:
        float: A área do triângulo.
    """
    return (base * altura) / 2

Exemplo de uma classe com Docstring

class Retangulo:
    """Representa um retângulo.

    Atributos:
        largura (float): A largura do retângulo.
        altura (float): A altura do retângulo.
    """

    def __init__(self, largura, altura):
        self.largura = largura
        self.altura = altura

    def area(self):
        """Calcula a área do retângulo."""
        return self.largura * self.altura

Dicas para escrever boas Docstrings

Escrever boas Docstrings é uma habilidade que, com o tempo e a prática, pode ser aprimorada. Dessa forma, aqui estão algumas dicas úteis para ajudá-lo nesse processo.

O que incluir em uma Docstring

• Descrição clara do que a função, classe ou módulo faz.
• Descrição dos parâmetros e seus tipos.
• O que a função retorna e seu tipo.
• Exceções que a função pode levantar, se aplicável.

O que evitar em uma Docstring

• Evite ser vago ou genérico. Seja específico sobre o que a função faz.
• Não inclua informações desnecessárias ou redundantes.
• Evite jargões técnicos que possam confundir iniciantes.

Conclusão

Neste guia, exploramos o que são Docstrings em Python, sua importância e como criá-las. Acessamos Docstrings e analisamos exemplos práticos de uso. As Docstrings são uma ferramenta poderosa para documentar nosso código e facilitar sua manutenção, tornando-o mais compreensível para nós e para outros desenvolvedores.

Se você desejar continuar sua jornada de aprendizado em Python, pode, por exemplo, explorar novos tópicos, como a manipulação de arquivos ou a criação de funções mais complexas. Além disso, é importante lembrar que a prática é essencial. Assim, quanto mais você se familiarizar com a linguagem, mais simples será escrever um código limpo e bem documentado..

Referências

• DataCamp: Docstrings em Python

Curso Gratuito

Seu primeiro projeto Python – curso grátis com certificado!

Vá do zero ao primeiro projeto em apenas 2 horas com o curso Python para Iniciantes.

Comece agora