Revisão de código e padrão

Padrão escrito é padrão citável

Trabalho num parque com padrão de código formalizado: dezenas de regras escritas para backend e frontend, versionadas e disponíveis nos repositórios. Participo da manutenção desse conjunto.

A diferença entre padrão escrito e padrão combinado é o que acontece na revisão. Com regra escrita, o apontamento é “isto contraria a regra X, que diz textualmente Y”. Sem ela, é “eu faria diferente” e aí a discussão vira quem tem mais senioridade, não o que é melhor para o código.

Como eu reviso

• Agrupo por regra, não por arquivo. Decidir “todos os sete casos de X” é uma decisão; decidir arquivo por arquivo são sete discussões sobre a mesma coisa
• Cito a regra literalmente, com o arquivo onde ela está
• Separo o que é regra do que é opinião. Se não está escrito, vai marcado como sugestão, não como não-conformidade
• Digo o que não consegui avaliar. Arquivo grande demais, regra que depende de contexto que eu não tenho: silêncio sobre isso é pior que a lacuna
• Não modifico nada sem confirmação. Revisão aponta; quem decide é o autor

Quando a regra parece errada

Acontece. Nesse caso eu não forço o código a obedecer em silêncio, nem ignoro em silêncio: aponto que a regra parece inadequada para o caso, digo por quê, e a discussão vira sobre a regra. Regra que ninguém questiona vira burocracia; regra que qualquer um ignora não é regra.

Automatizar a parte mecânica

Parte das regras é verificável por ferramenta e roda como verificação automática antes do commit. O que sobra para a revisão humana é o que exige julgamento: modelagem, nome, fronteira de responsabilidade. Gastar atenção humana no que o computador resolve é desperdício dos dois lados.

Escrever regra para ser lida por máquina tem exigência própria, e ela está em Padrão que a máquina consome.