Programação Por Equipe DevBras

Capa do artigo: Nome de função que mente: validar que grava, buscar que cria

Nome de função que mente: validar que grava, buscar que cria

Nome de função que mente engana quem chama: como separar pergunta de comando, renomear sem quebrar o código antigo e testar que a pergunta não grava nada.

Uma desenvolvedora recém-chegada ao time da Torrefação Serra Azul queria entender as mensagens de erro do checkout. Abriu o terminal do Django, montou um pedido de teste e chamou validar_pedido(pedido). A função devolveu uma lista vazia, ótimo. Na manhã seguinte, o financeiro perguntou quem era o cliente "Teste da Silva", que tinha um pedido confirmado e um e-mail de confirmação enviado. A função não só validava: quando estava tudo certo, mudava o status para confirmado, gravava no banco e disparava o e-mail.

Ninguém lê o corpo de toda função que chama. Num projeto de tamanho médio, quem usa uma função confia no nome, na assinatura e, com sorte, na docstring. O nome é o contrato mais curto do código, e o verbo desse nome precisa descrever o efeito real. Este guia mostra como reconhecer um nome que promete menos do que entrega e como consertar sem quebrar quem já chama a função.

Os nomes que mais mentem

Alguns padrões aparecem em quase todo código legado. Vale procurar por eles numa revisão:

  • Verbo de consulta com efeito. validar_*, verificar_*, checar_*, calcular_* que gravam, enviam ou alteram o objeto recebido.
  • Buscar que cria. get_usuario(email) que cadastra o usuário quando não encontra. Quem chamou para saber se a pessoa existe acabou de criar uma conta.
  • Nome no singular que processa em lote, ou o contrário: enviar_lembrete(cliente) que, na verdade, envia para todos os clientes do mesmo grupo.
  • Booleano que não diz o lado. status_ok que é verdadeiro quando há erro, ou ativo que significa "bloqueado" num módulo antigo.
  • Nome que sobreviveu à mudança. salvar_rascunho que, depois de três sprints, também publica.

O último é o mais comum. A função nasceu honesta, ganhou responsabilidades em pull requests pequenos e ninguém atualizou o nome, porque mudar o nome parecia trabalho demais para um ajuste de duas linhas.

A regra que separa os casos: pergunta ou comando

Bertrand Meyer formulou a separação entre consulta e comando: um método ou responde uma pergunta, ou muda o estado do sistema, mas não as duas coisas. Martin Fowler resume a ideia no verbete CommandQuerySeparation, com a ressalva de que há exceções úteis, como tirar um item de uma pilha. A regra prática que vem dela:

  • Se a função responde, o nome descreve a resposta, e chamá-la duas vezes não muda nada. erros_do_pedido, total_com_frete, esta_vencido.
  • Se a função muda o mundo, o verbo diz o que muda. confirmar_pedido, enviar_convite, cancelar_assinatura.
  • Se a exceção for proposital, ela aparece no nome. O Django faz isso com o get_or_create, que devolve o objeto e um booleano dizendo se criou. Ninguém se surpreende com o efeito, porque ele está escrito.

A PEP 8 cuida da forma dos nomes em Python, como minúsculas com sublinhado para funções. O significado do verbo é por sua conta e do time.

Consertando o validar_pedido sem quebrar ninguém

A versão original fazia três coisas sob um nome que anunciava uma:

def validar_pedido(pedido):
    erros = []
    if not pedido.itens:
        erros.append("Pedido sem itens.")
    if pedido.total_centavos <= 0:
        erros.append("Total precisa ser maior que zero.")
    if not erros:
        pedido.status = "confirmado"
        db.session.commit()
        enviar_email_confirmacao(pedido)
    return erros

O conserto seguiu quatro passos, que servem para qualquer função suspeita.

1. Liste os efeitos reais

Leia o corpo e anote tudo que sai da função: gravação no banco, chamada HTTP, e-mail, arquivo, fila, alteração no objeto recebido. Aqui: altera pedido.status, faz commit e envia e-mail. Siga também as funções chamadas lá dentro, porque o efeito escondido às vezes está um nível abaixo.

2. Separe a pergunta do comando

class PedidoInvalido(Exception):
    def __init__(self, erros):
        super().__init__("; ".join(erros))
        self.erros = erros

def erros_do_pedido(pedido) -> list[str]:
    erros = []
    if not pedido.itens:
        erros.append("Pedido sem itens.")
    if pedido.total_centavos <= 0:
        erros.append("Total precisa ser maior que zero.")
    return erros

def confirmar_pedido(pedido) -> None:
    erros = erros_do_pedido(pedido)
    if erros:
        raise PedidoInvalido(erros)
    pedido.status = "confirmado"
    db.session.commit()
    enviar_email_confirmacao(pedido)

erros_do_pedido pode ser chamada quantas vezes quiser, inclusive no terminal, sem consequência. confirmar_pedido deixa claro, pelo verbo, que algo vai acontecer, e recusa pedido inválido com uma exceção que carrega a lista de erros.

3. Mantenha o nome antigo como ponte

Se a função é chamada em muitos lugares, ou por outro time, renomear tudo num commit só é arriscado. Deixe o nome antigo chamando os novos, com um aviso de que vai sair:

import warnings

def validar_pedido(pedido):
    warnings.warn(
        "validar_pedido vai sair: use erros_do_pedido ou confirmar_pedido",
        DeprecationWarning, stacklevel=2)
    erros = erros_do_pedido(pedido)
    if not erros:
        confirmar_pedido(pedido)
    return erros

O comportamento antigo fica igual, e o DeprecationWarning aponta, com stacklevel=2, a linha de quem chamou, e não a da ponte. O módulo warnings permite transformar o aviso em erro numa rodada de testes, com python -W error::DeprecationWarning, para achar os chamadores que sobraram. Quando não sobrar nenhum, a ponte sai.

4. Teste que a pergunta não tem efeito

O teste que faltava era justamente o que pegaria a mentira: chamar a consulta e conferir que nada mudou. Com uma sessão falsa que conta commits e uma lista no lugar do envio de e-mail, rodei estes testes no Python 3:

p = Pedido(["café 250 g"], 4590)
assert erros_do_pedido(p) == []
assert p.status == "rascunho" and db.commits == 0 and emails == []

confirmar_pedido(p)
assert p.status == "confirmado" and db.commits == 1 and len(emails) == 1

vazio = Pedido([], 0)
try:
    confirmar_pedido(vazio)
    raise AssertionError("devia recusar")
except PedidoInvalido as e:
    assert e.erros == ["Pedido sem itens.", "Total precisa ser maior que zero."]
assert db.commits == 1   # a recusa não gravou nada

Os quatro blocos passaram, inclusive o que confere que a ponte validar_pedido emite o DeprecationWarning. Repare que o teste afirma resultados, e não só chama a função. Um teste sem afirmação passaria pelas linhas e deixaria a cobertura em 100% sem pegar nada, o problema descrito em cobertura sem assert.

Quando o nome certo fica comprido

Às vezes o nome honesto é confirmar_pedido_e_reservar_estoque_e_avisar_cliente. Isso não é problema de nome: é a função dizendo que faz coisas demais. As saídas são duas. Ou ela vira uma orquestração com nome de caso de uso, como finalizar_checkout, e chama funções menores com nomes honestos, ou as partes são separadas e quem chama decide a ordem.

O mesmo vale para parâmetros que mudam o comportamento. processar(pedido, True, False) esconde no booleano a mentira que o nome não conta; o guia sobre parâmetro booleano solto mostra como trocar isso por nomes. E, quando um nome honesto ainda não explica por que a função existe, um comentário curto sobre o motivo ajuda, como em o que escrever num comentário.

Na revisão de código, uma pergunta simples pega boa parte desses casos: "se eu chamar isto duas vezes, o que acontece?". Se a resposta for "nada", o nome pode ser de pergunta. Se for "manda dois e-mails", o nome precisa dizer que manda. Mudanças desse tipo ficam mais fáceis de revisar em PRs pequenos, um nome por vez, como defende revisão de PR pequeno.

Avalie este artigo

Referência: https://www.python.org/dev/peps/pep-0008/#naming-conventions