Documentando Código Python: Docstrings e Type Hints

Documentar seu código Python com Docstrings (para explicar o “o quê” e “porquê” de funções, classes e módulos) e Type Hints (para indicar os tipos de dados esperados) é crucial para ter um código claro, fácil de manter e que parece profissional. É o seu código “falando” por si mesmo!

Por Que a Documentação Não É Perda de Tempo

Sabe quando você tenta montar um móvel sem o manual de instruções? É frustrante, demorado e a chance de sobrar uma peça é grande! Escrever código sem documentação é a mesma coisa.

A documentação é o “manual de instruções” do seu código. Ela explica o propósito, a forma de uso e o resultado esperado de cada parte. Isso é vital, não só para quem for trabalhar com seu código depois (seja um colega ou seu “eu” do futuro), mas também para você mesmo enquanto desenvolve, garantindo que tudo está claro.

Em Python, temos duas ferramentas de destaque para isso: Docstrings e Type Hints. Vamos ver como usá-las para elevar o nível do seu código, especialmente com foco em como usar type hints para garantir o que entra e sai das funções.

📝 Docstrings: O Manual de Instruções do Seu Código

Imagine o Docstring como o rótulo de um pote na sua despensa. Você não quer abrir todos os potes para saber se tem açúcar ou farinha, certo? O Docstring é esse rótulo.

Uma Docstring (do inglês, Documentation String) é uma string de múltiplas linhas colocada logo na primeira linha após a definição de um módulo, classe, função ou método. Ela descreve:

• O que faz: O propósito daquele bloco de código.
• Como usar: Quais parâmetros espera e o que retorna.

🌟 Estrutura Básica de uma Docstring

Usamos aspas triplas (""") para as docstrings. Embora existam vários estilos (Google, NumPy, reST), o mais importante é ser consistente e claro. O formato mais simples inclui uma frase de resumo, e uma seção para os argumentos e o retorno. Veja um exemplo de docstring abaixo:

def calcular_quadrado(numero):
    """
    Calcula o quadrado de um número inteiro.

    Args:
        numero (int): O número inteiro a ser elevado ao quadrado.

    Returns:
        int: O resultado do número elevado ao quadrado.
    """
    resultado = numero * numero
    return resultado

🎯 Type Hints (Dicas de Tipo): A Receita Completa

Se a docstring é o rótulo, os Type Hints são os ingredientes exatos da receita!

Type Hints são anotações que adicionamos ao código Python para indicar o tipo esperado de variáveis, parâmetros de função e o valor de retorno de uma função. Por exemplo, se uma função espera um número, nós anotamos isso.

Importante: Python é uma linguagem de tipagem dinâmica, o que significa que o interpretador não força você a usar o tipo correto com base nos type hints. Eles servem principalmente para:

1. Clareza e Legibilidade: Deixam o código mais fácil de entender rapidamente.
2. Ferramentas de Análise Estática: Ferramentas como o Mypy podem checar seu código antes da execução para encontrar erros de tipo.

🔑 Tipando Parâmetros e Retornos de Função

Vamos ver a sintaxe para usar as type hints:

• Parâmetros de Função: Colocamos dois pontos (:) após o nome do parâmetro, seguido pelo tipo.
• Retorno de Função: Usamos uma seta (->) após a lista de parâmetros, seguido pelo tipo de retorno.

# Tipando o parâmetro e o retorno da função
def calcular_quadrado(numero: int) -> int:
    """
    Calcula o quadrado de um número inteiro.

    Args:
        numero (int): O número inteiro a ser elevado ao quadrado.

    Returns:
        int: O resultado do número elevado ao quadrado.
    """
    resultado = numero * numero
    return resultado

# Tipando o valor de uma variável
meu_numero: int = 14

# Tipando uma variável com mais de um tipo possível
variavel_que_pode_ser_nula: (str | None) = None

Em casos que um parâmetro de função, variável ou retorno possam ser de mais de um tipo, utilize o operador | para indicar as possibilidades de tipo.

Tipos Complexos

Para tipos complexos como listas e dicionários precisamos importar a biblioteca typing do python. Veja o exemplo:

from typing import List, Dict

numeros_pares: List[int] = [2, 4, 6, 8, 10]

cardapio: Dict[str, float] = {
    "Feijão com Arroz e Carne": 24.99,
    "Lasanha": 28.79
}

⚠️ Erros Comuns / Armadilhas

• Docstring Vazia ou Inconsistente: Colocar a Docstring, mas não atualizá-la quando a função muda, ou escrever algo muito vago.
• Usar Type Hints como Documentação Única: O Type Hint mostra o tipo esperado, mas não o porquê ou o contexto. A Docstring é essencial para o contexto.

✅ Boas Práticas / Dicas Rápidas

• Seja Conciso na Docstring: A primeira linha deve resumir o que o código faz em uma única frase.
• Use Mypy: Se você está usando type hints, considere instalar e rodar o Mypy no seu código para checar se os tipos estão sendo usados corretamente antes de executar.
• Padrão de Tipo: Para tipos de dados simples, como int ou str, o type hint é o suficiente. Para estruturas de dados complexas, use a notação de Docstring para explicar o que os elementos significam.
• Comece Agora: Adicione Docstrings e Type Hints a todas as novas funções e classes que você criar. Não espere!

🚀 Conclusão

Dominar a arte da documentação com Docstrings e Type Hints é um divisor de águas na sua jornada de desenvolvimento. Não se trata apenas de estética, mas de profissionalismo, clareza e manutenção. Ao adotar essas práticas, você transforma seu código em algo que não só funciona, mas é um prazer de ler e evoluir.

Para quem busca ser um especialista Python, o livro Curso Intensivo de Python: uma Introdução Prática e Baseada em Projetos à Programação ensina python com projetos práticos que resolvem problemas reais. Ao adquirir o livro através deste link, você não só investe no seu conhecimento, como também apoia o blog Dev Explica, ajudando a manter a produção de conteúdo didático e de qualidade!

Compre aqui “Curso Intensivo de Python: uma Introdução Prática e Baseada em Projetos à Programação”