Pull requests não são comentários: Chen lembra o óbvio que falta

Quem vive enfiado no GitHub já se habituou a ver tudo baralhado no mesmo saco: descrição de pull request, mensagem de commit e comentários no código. Raymond Chen, engenheiro veterano da Microsoft, veio lembrar que isto não é tudo a mesma coisa. E que essa confusão cobra juros, sobretudo agora que as IA de programação debitam PRs como se fossem spam.

No seu blogue The Old New Thing, Chen define a descrição de um pull request como um enunciado de momento único. Serve o ciclo de revisão, não o futuro arquivista do repositório. O objectivo é quase retórica: tens de convencer quem aprova que a alteração faz sentido. Que problema resolves, por que escolheste esta abordagem em vez de outra, que riscos introduces, que testes correste. É o memo de decisão da mudança, não o manual de instruções da função.

Já os comentários no código são outra conversa. São para falar do próprio código, de preferência do que não é óbvio: como chamar esta função sem partir nada, pré-condições que não cabem na assinatura, hacks que dependem de um bug histórico de uma API. Essa informação tem de sobreviver muito para lá do merge, exactamente o oposto da descrição da PR, que se torna ruído passado pouco tempo. Meter contexto de negócio de três páginas dentro de um comentário é uma forma elegante de o enterrar.

Curiosamente, Chen nem entra a fundo num terceiro elemento que devia estar ao nível destes dois: a mensagem de commit. Em muitos projectos portugueses e europeus continua tratada como caixote do lixo de “fix” e “update”. É aí que devia viver o resumo conciso do o quê e do porquê da alteração, para quem faz blame ou bisect daqui a três anos. A descrição da PR ajuda o revisor hoje, o comentário ajuda quem lê o código, o commit ajuda quem investiga a história. Misturar papéis é receita para arqueologia de Git.

O tema ganha outra camada com IA generativa a escrever tanto código como prosa. Já começam a aparecer PRs completos produzidos por assistentes de código, com descrições vagas e comentários cheios de banalidades ou, pior, de mentiras confiantes. A mesma pressão que está a encostar a revisão por pares à beira da rutura também chega aqui: reviewers sobrecarregados, diffs gigantes, confiança excessiva na ferramenta. Quando o autor humano nem percebe bem o patch que o bot sugeriu, a probabilidade de a descrição da PR ser honesta e útil cai a pique.

Há ainda o lado cultural que Chen toca de raspão, via discussões eternas como tabs vs espaços ou guerras de estilo. O conselho dele é desarmante: não interessa muito a tua estética, interessa mais não encobrir a lógica com mudanças de formatação. Se queres alinhar tudo com a nova guideline da empresa, faz um check-in separado para isso, não escondas o bugfix no meio de mil linhas reindentadas. Para equipas em Portugal, muitas vezes mistas entre consultoras, nearshore e freelancers, esta disciplina básica vale mais do que mais uma ferramenta da moda. O revisor precisa de uma história clara na PR, o futuro mantenedor precisa de comentários decentes, e o Git precisa de commits que não sejam apenas um grunhido. O resto é ruído.

Fonte: The Register