Descrições de código precisam ser simples

Commit messages e descrições de pull requests não são notas de rodapé, são a primeira porta de entrada para quem vai revisar seu código. Quando o texto vira um relatório detalhado de tudo o que foi alterado, o revisor perde o foco no que realmente importa: o porquê da mudança. O código já mostra o que foi feito. A explicação precisa ser sobre o motivo, o contexto, a intenção. Isso não é só questão de estilo. É sobre eficiência, inclusão e manutenção. Desenvolvedores com TDAH, autistas ou qualquer um que precise de clareza cognitiva não conseguem navegar em textos densos. E mesmo quem não tem diagnóstico se cansa de ler parágrafos que poderiam ser uma frase.

Revisar código exige atenção fragmentada. Um commit atômico, com mensagem direta, permite que a revisão aconteça em pedaços pequenos. Se a mudança é complexa, ela deve ser dividida. Se a explicação está faltando, pergunte. Não encha o texto com detalhes que o próprio código já mostra. A ferramenta mais poderosa que você tem não é o LLM, é sua capacidade de pensar e explicar com precisão. E isso vale mais do que qualquer geração automática.

Quando descrições de código são confusas ou excessivas, o custo de manutenção sobe. Equipes inteiras perdem tempo decifrando o que realmente mudou. Isso atrasa releases, aumenta bugs e desgasta a cultura de revisão. Em projetos grandes, onde centenas de commits rodam por dia, a clareza não é opcional, é infraestrutura. Escrever bem não é ser perfeccionista. É ser respeitoso com quem vem depois de você. E isso inclui você, daqui a seis meses, tentando lembrar por que aquele if foi adicionado.