Documentação e
testes unitários

Ao final, você será capaz de.

O código é o edifício, a documentação é a planta

Imagine um engenheiro que entrega um prédio pronto, mas sem a planta arquitetônica nem o mapa elétrico. Anos depois é preciso trocar um cano: os operários vão quebrar as paredes às cegas.

Comentário é o "porquê", não o "como"

Comentar cada linha traduzindo a sintaxe é ruído: o leitor já sabe ler Python. O comentário só se paga quando conta algo que o código não consegue dizer sozinho.

O comentário que vale ouro

Use comentários para justificar decisões de negócio que a sintaxe não revela. Números mágicos, exceções à regra, contornos temporários: tudo isso precisa de origem documentada.

valor_final = preco * 1.15

# Fator 1.15 aplicado por causa da alteração
# na Lei Tributária 1234 (agosto/2025).
valor_final = preco * 1.15

O contrato da função

A docstring é o texto entre aspas triplas na primeira linha de uma função, classe ou módulo. Ela formaliza a interface pública: o que entra, o que sai, o que pode dar errado.

Como se escreve na prática

def calcular_area(raio):
    """
    Calcula a área de um círculo.

    Args:
        raio (float): O raio do círculo.

    Returns:
        float: A área do círculo.

    Raises:
        ValueError: se o raio for negativo.
    """
    if raio < 0:
        raise ValueError("Raio negativo")
    return 3.14 * raio ** 2

print(calcular_area.__doc__)
help(calcular_area)

Calcula a área de um círculo.

Args:
    raio (float): O raio do círculo.

Returns:
    float: A área do círculo.
...

Comentário x docstring

Qual é a distinção fundamental?

Entre um comentário comum e uma docstring, no contexto do desenvolvimento de software:

Documentação que se escreve sozinha

Porque a docstring é um dado acessível pelo programa, ferramentas conseguem varrer o projeto inteiro e montar um manual navegável a partir dela.

Documentação errada é pior que nenhuma

Quando o código muda e a docstring fica para trás, ela deixa de ser ajuda e vira armadilha: o leitor confia em uma promessa que o programa não cumpre mais.

def aplicar_desconto(preco):
    """Aplica 10% de desconto."""
    return preco * 0.80   # mudou para 20%

O efeito dominó no código

A docstring diz que a função aplica 10% de desconto. Mas quem garante que ela ainda faz isso depois da alteração de ontem? Você corrige um erro no login, testa, funciona — e sem perceber quebra a finalização de compras.

A menor engrenagem do sistema

O poder do isolamento

Pense em uma fábrica de carros. Como sabemos se o motor funciona? Ligamos o motor isolado, numa bancada, antes de instalar no carro. Se falhar, o problema é no motor — não no pneu.

Todo teste tem três atos

Como o assert se comporta

O assert é nativo do Python: avalia uma condição; se for verdadeira, o programa continua em silêncio; se for falsa, ele trava e lança um AssertionError.

assert 2 + 2 == 4          # passa, silêncio
assert 2 + 2 == 5, "Erro na soma!"

Traceback (most recent call last):
  File "teste.py", line 2, in <module>
AssertionError: Erro na soma!

Provando que o desconto fecha

Você é da equipe de qualidade de um e-commerce. O setor financeiro exige provas de que a função de desconto é infalível.

def calcular_desconto(valor_original, percentual):
    """Devolve o valor já com o desconto aplicado."""
    desconto = valor_original * (percentual / 100)
    return valor_original - desconto

def testar_calculo_de_desconto():
    # 1. Arrange (preparar)
    valor_produto = 200.0
    desconto_aplicado = 15.0
    resultado_esperado = 170.0   # gabarito

    # 2. Act (agir)
    resultado_obtido = calcular_desconto(
        valor_produto, desconto_aplicado)

    # 3. Assert (validar)
    assert resultado_obtido == resultado_esperado, \
        "Erro matemático grave no desconto!"
    print("Sucesso! O teste unitário passou.")

testar_calculo_de_desconto()

Verde, vermelho e nada no meio

Sucesso! O teste unitário passou.

Traceback (most recent call last):
  File "teste.py", line 14, in testar_calculo_de_desconto
AssertionError: Erro matemático grave no desconto!

No padrão AAA, o que faz o assert?

Um teste só não basta

Testar apenas o caso que você já sabe que funciona dá falsa sensação de segurança. Um bom conjunto cobre três frentes:

Três testes, um segundo

def testar_sem_desconto():
    assert calcular_desconto(200, 0) == 200, \
        "0% deveria manter o valor"

def testar_desconto_total():
    assert calcular_desconto(200, 100) == 0, \
        "100% deveria zerar o valor"

def testar_desconto_comum():
    assert calcular_desconto(200, 15) == 170, \
        "15% de 200 deveria dar 170"

# executor simples da suíte
for teste in (testar_sem_desconto,
              testar_desconto_total,
              testar_desconto_comum):
    teste()
    print("OK:", teste.__name__)

OK: testar_sem_desconto
OK: testar_desconto_total
OK: testar_desconto_comum

Qual destes não é um teste unitário?

Documentar e provar a mesma função

Documentação e testes em oito linhas

• # comenta uma linha · """…""" logo abaixo do def vira docstring
• Docstring: o que faz → Args → Returns → Raises
• Antes de comentar, tente renomear a variável; mudou o código, muda a documentação
• assert condicao, "mensagem" — a menor forma de teste em Python
• Ordem sagrada: Arrange → Act → Assert
• Um teste, um comportamento; o nome do teste descreve o que se espera
• Gabarito calculado na mão, nunca pela mesma fórmula que está sendo testada
• Achou um bug? Escreva primeiro o teste que o reproduz, depois corrija