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_okque é verdadeiro quando há erro, ouativoque significa "bloqueado" num módulo antigo. - Nome que sobreviveu à mudança.
salvar_rascunhoque, 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.
Referência: https://www.python.org/dev/peps/pep-0008/#naming-conventions