Mensagens de commit com o sujeito primeiro
O debate entre mensagens de commit “subject-first” e o tradicional estilo verbo-primeiro destaca o quanto as equipes usam o histórico de controle de versão de maneiras diferentes. Alguns engenheiros percorrem logs e querem assuntos concisos que coloquem em primeiro plano o componente ou comportamento afetado, enquanto outros raramente revisitam commits e veem formatos rígidos como bikeshedding de baixo retorno em comparação com diffs, PRs e rastreadores de issues. A discussão levanta perguntas mais profundas sobre se as mensagens de commit devem servir прежде tudo a pessoas ou a ferramentas, quanto do “porquê” deve ficar no Git versus em sistemas de tickets, e como escolhas de fluxo de trabalho (por exemplo, squash merges, pairing, sem PRs) moldam o que uma mensagem de commit “boa” significa.
Com que frequência o histórico de commits é usado
- As experiências divergem bastante. Alguns dizem que quase nunca leem mensagens antigas de commit em anos de trabalho; outros relatam usar o histórico ou o blame semanalmente, ou até diariamente.
- Usos comuns: depuração (“por que este código é assim?”), rastrear quando o comportamento mudou, fazer bisect para regressões e entender o impacto em linhas/arquivos específicos.
- Vários argumentam que as mensagens raramente acrescentam mais do que o diff e muitas vezes são de baixa qualidade (“wip”, “update”), o que desincentiva confiar nelas.
O que boas mensagens de commit devem conter
- Muitos querem que as mensagens de commit registrem o “porquê” e o “o quê” em alto nível, deixando o diff fornecer o “como” detalhado.
- Um assunto curto e escaneável, mais um corpo detalhado opcional, é um padrão amplamente apreciado.
- Alguns veem as mensagens de commit principalmente como algo para seu próprio trabalho intermediário; outros, como documentação compartilhada de longo prazo e fonte de changelog.
- A consistência entre a equipe costuma ser vista como mais importante do que qualquer estilo específico.
Estilos sujeito-primeiro vs verbo-primeiro
- A favor do sujeito-primeiro: colocar primeiro a parte mais variável/importante (o sujeito/componente afetado) supostamente melhora a leitura rápida, de forma semelhante ao design de listas e a insights de rastreamento ocular.
- Os críticos contestam tanto a legibilidade quanto a base psicológica alegada, argumentando que verbos/ações são o que importa (“o que mudou”) e que os exemplos são vagos demais.
- Alguns preferem formatos com prefixo de componente ou conventional commits (
type(scope): summary), que categorizam mudanças e dão suporte a ferramentas.
Mensagens de commit vs tickets e outros artefatos
- Muitos enfatizam incluir IDs de tickets para ligar a contexto mais rico de negócio e discussão; outros não gostam de IDs nos títulos, preferindo-os no corpo ou em trailers.
- Vários alertam que sistemas de tickets e URLs mudam ou desaparecem, tornando IDs ou links apenas no commit frágeis; eles defendem explicações de commit autocontidas.
- Uma equipe descreve um método mais amplo: sem pull requests, muita pair programming/mobbing, arquivos de texto e registros de equipamentos no git, e mensagens de commit principalmente como índices concisos, com sujeito primeiro.
Meta: valor e bikeshedding
- Alguns veem debates sobre estilo de commit como bikeshedding de baixo retorno em comparação com problemas de produto.
- Outros argumentam que mensagens ruins causam perda significativa de tempo no longo prazo e que um pouco de disciplina aqui compensa.