Como escrever comentários sobre confirmações

Prefácio do tradutor

Ao longo dos anos de desenvolvimento de software, sendo membro de muitas equipes, trabalhando com várias pessoas boas e experientes, observei com frequência (e para ser honesto, criei) o mesmo problema - uma bagunça total no repositório. Cada um escreveu comentários sobre commits em seu próprio estilo (e bem, se constantemente em um); metade dos comentários foi inútil (da categoria " isto é uma ponte "), metade da metade restante não foi compreendida.

E então, um belo momento, vi este artigo, antes do qual finalmente pus minhas mãos na tradução. Apenas 7 regras simples e breves, e - eis - observar o histórico dos commits não foram apenas úteis, mas também agradáveis. Nada revolucionário, tudo é bastante óbvio, mas formulado e resumido muito bem.

Quero observar que este é um artigo de 2014. Algumas coisas não muito relevantes mencionadas pelo autor podem perder relevância, mas a essência do artigo não é de todo.

Introdução: Por que bons comentários são importantes

Se você procurar em um repositório Git aleatório, provavelmente encontrará que há algum tipo de confusão no histórico de consolidação. Por exemplo, dê uma olhada nessas pérolas desde o momento em que comecei a enviar para o repositório Spring:

 $ git log --online -5 --autor cbeams - antes de "sexta-feira 26 de março de 2009"

 e5f4b49 Re-adicionando o ConfigurationPostProcessorTests após sua breve remoção na r814.  @ Ignorando o método testCglibClassesAreLoadedJustInTimeForEnhancement (), pois esse foi um dos culpados na recente quebra de compilação.  O hacker do carregador de classes causa efeitos sutis a jusante, interrompendo testes não relacionados.  O método de teste ainda é útil, mas deve ser executado apenas manualmente, para garantir que o CGLIB não seja carregado prematuramente na classe e não deve ser executado como parte da construção automatizada.
 2db0f12 corrigiu dois problemas de quebra de compilação: + ClassMetadataReadingVisitor revertido para a revisão 794 + ConfigurationPostProcessorTests eliminado até uma investigação mais aprofundada determinar por que causa a falha nos testes posteriores (como ClassPathXmlApplicationContextTests) aparentemente não relacionado
 147709f Ajustes nos arquivos package-info.java
 22b25e0 Classes Util e MutableAnnotationUtils consolidadas em AsmUtils existentes
 Polimento 7f96f57

Horror. Compare com esses commits mais recentes no mesmo repositório:

 $ git log --online -5 --autor do pwebb - antes de "Sáb 30 de agosto de 2014"

 5ba3db6 Correção com falha CompositePropertySourceTests
 84564a0 Retrabalhe a lógica de análise inicial de @PropertySource
 e142fd1 Adicione testes para os metadados ImportSelector
 887815f Atualize a dependência do livro de documentos e gere epub
 ac8326d uso de mockito polonês

Qual opção você prefere?

Os primeiros variam em tamanho e estilo, os segundos são concisos e homogêneos.
O primeiro é obtido por si só, o segundo é escrito conscientemente.

E embora o histórico de consolidação de muitos repositórios pareça a primeira opção, há exceções. Bons exemplos são o kernel do Linux e o próprio Git . Dê uma olhada no Spring Boot ou em qualquer outro repositório com o qual Tim Pope lide.

Os participantes desses projetos sabem que um comentário bem escrito sobre o commit é a melhor maneira de contar o contexto das alterações feitas em outros desenvolvedores (e também em si mesmos no futuro). As diferenças nas revisões mostram o que mudou, mas apenas um comentário pode explicar claramente o porquê . Peter Hutterer disse bem :

Recuperar da codificação é uma perda de tempo. Não podemos evitá-lo completamente, portanto nossos esforços devem se concentrar em minimizar esses custos. É para isso que servem os comentários sobre confirmações. Portanto, eles mostram se o programador funciona bem em equipe.

Se você realmente não pensou sobre o que deveria ser um comentário de confirmação de primeira classe, provavelmente não usou o git log e ferramentas semelhantes com muita frequência. Existe um círculo vicioso: como a história dos commits é desestruturada e heterogênea, eles não o usam e nem prestam atenção. E devido ao fato de não o usarem e não prestarem atenção, ele permanece não estruturado e heterogêneo.

Mas uma história de repositório bem projetada é uma coisa bonita e útil. Os comandos git blame , revert , rebase , log , shortlog e outros ganham vida . Faz sentido examinar os pedidos de confirmação e recebimento de outras pessoas e, de repente, agora a ajuda de seus autores não é mais necessária. Para entender por que algo aconteceu [no código] meses ou anos atrás, torna-se não apenas possível, mas também conveniente.

O sucesso a longo prazo do projeto depende (entre outras coisas) de como é conveniente manter, e o histórico de confirmações é uma das ferramentas mais poderosas do mantenedor. Vale a pena gastar tempo aprendendo a manter a ordem. No início, isso pode causar algum inconveniente, mas depois se tornará um hábito e, no final, se tornará uma fonte de orgulho e trabalho produtivo para todos os participantes.

Este artigo aborda apenas o componente mais básico da manutenção de uma boa história, como escrever um comentário em um commit separado. Há outras coisas importantes, como mesclar confirmações que não são abordadas aqui.

A maioria das linguagens de programação possui convenções geralmente aceitas e bem descritas que formam um estilo distinto [de escrever código], como nomes de variáveis, regras de formatação e assim por diante. Obviamente, existem versões diferentes desses acordos, mas a maioria dos desenvolvedores é de opinião que escolher uma opção e segui-la é muito melhor do que uma bagunça quando todos escrevem em seu próprio estilo.

A abordagem da equipe para descrever os commits deve ser exatamente a mesma. Para que a história do repositório seja útil, a equipe deve chegar a um acordo sobre pelo menos os três pontos a seguir.

Estilo. Sintaxe de marcação, recuo, quebras de linha, gramática, letras maiúsculas, pontuação. Verifique sempre a ortografia e escreva o mais fácil possível. Como resultado, você obterá um histórico surpreendentemente completo de confirmações, que não é apenas agradável de ler, mas que você realmente lerá regularmente.

Conteúdo Quais informações (se houver) devem estar contidas no corpo do comentário? Por que não deveria estar lá?

Metadados Como devo me referir a IDs de tarefas, números de solicitação pull, etc.?

Felizmente, já existem acordos para escrever um comentário significativo. De fato, eles decorrem parcialmente da maneira como alguns comandos do Git funcionam. Você não precisa reinventar a roda. Basta seguir as sete regras abaixo - e você estará um passo mais perto da história dos compromissos dignos de um profissional.

Sete regras para um comentário legal de confirmação

Lembre-se: Tudo isso foi dito antes .

1. Separe o cabeçalho do corpo com uma sequência vazia
2. Limite o título a 50 caracteres
3. Capitalizar o título
4. Não coloque um ponto no final do título
5. Use o imperativo no título.
6. Vá para a próxima linha do corpo com 72 caracteres
7. No corpo, responda às perguntas sobre o que e por quê , e não como

Por exemplo:

 Resuma alterações em 50 caracteres ou menos

 Aqui, explique-os com mais detalhes, se necessário.  Acompanhamento
 quebras de linha de aproximadamente 72 caracteres.  Em algumas situações
 a primeira linha do comentário é considerada seu título e todas 
 o resto é com o corpo.  É imperativo separar para separar um do outro
 uma string vazia (se a mensagem tiver um corpo, é claro);
 várias ferramentas como `log`,` shortlog` e `rebase` não entenderão
 você se o cabeçalho e o corpo não estiverem separados.

 Explique aqui que problema esse commit resolve.  Leve embora 
 mais atenção ao motivo pelo qual você fez essas alterações, não para 
 exatamente como você fez isso (isso explicará o código para você).
 Existem efeitos colaterais ou outros efeitos não óbvios no 
 essas mudanças?  Nesse caso, isso precisa ser explicado aqui.

 Os parágrafos são separados por linhas em branco.

  - Você pode fazer listas com marcadores

  - Geralmente um asterisco ou 
    Um traço com um espaço na frente deles  mas existem acordos diferentes

 Se você possui um rastreador de erros [ou sistema de gerenciamento de projetos],
 coloque links de tarefas no final do texto da seguinte maneira:

 Resolvido: # 123
 Veja também: # 456, # 789

1. Separe o cabeçalho do corpo com uma string vazia

Do manual ao comando git commit :

Embora isso não seja necessário, é uma boa ideia iniciar um comentário no commit com uma linha curta (com menos de 50 caracteres) resumindo as alterações feitas, uma linha vazia e uma descrição mais detalhada. O texto antes da primeira linha vazia no comentário é considerado o cabeçalho da confirmação e é usado em diferentes comandos Git. Por exemplo, o Git-format-patch (1) transforma um commit em email; a equipe usa o cabeçalho do commit no assunto da carta e o restante do texto no corpo da carta.

Em primeiro lugar, nem todo commit requer um cabeçalho e um corpo. Às vezes, uma linha é suficiente, especialmente quando as alterações são tão pequenas que nenhuma informação adicional é necessária. Por exemplo:

  Corrigir erro de digitação na introdução ao guia do usuário 

Basta dizer; se o usuário quiser saber que tipo de erro de digitação foi corrigido, ele pode apenas observar as mudanças usando git show ou git diff ou git log -p .

Se você confirmar algo assim usando a linha de comando, será conveniente usar a opção -m para o git commit :

  $ git commit -m "Corrija erro de digitação na introdução ao guia do usuário" 

No entanto, quando o commit merece alguma explicação e descrição da situação, você precisa escrevê-los no corpo do comentário. Por exemplo:

 Derezz, o programa de controle principal

 O MCP acabou por ser mau e tinha se concentrado na dominação mundial.
 Este commit lança o disco de Tron no MCP (causando sua desesolução)
 e transforma de volta em um jogo de xadrez.

Comentários que possuem um corpo não são tão convenientes para escrever com a opção -m . Seria melhor usar um editor de texto para isso. Se você ainda não configurou o editor para uso com o Git, leia esta seção do livro Pro Git .

De qualquer forma, a separação do título e do corpo do comentário será recompensada ao visualizar o log. Aqui está o registro completo de confirmação:

 $ git log
 confirmar 42e769bdf4894310333942ffc5a15151222a87be
 Autor: Kevin Flynn <kevin@flynnsarcade.com>
 Data: Sex Jan 01 00:00:00 1982 -0200

  Derezz, o programa de controle principal

  O MCP acabou por ser mau e tinha se concentrado na dominação mundial.
  Este commit lança o disco de Tron no MCP (causando sua desesolução)
  e transforma de volta em um jogo de xadrez.

E aqui está o comando git log --oneline , que exibe apenas a linha do cabeçalho:

 $ git log --oneline
 42e769 Derezz, o programa de controle principal

Ou git shortlog, que grupos confirmam por autor, novamente, por questões de concisão, apenas mostra o título:

 $ git shortlog
 Kevin Flynn (1):
       Derezz, o programa de controle principal

 Alan Bradley (1):
       Introduzir o programa de segurança "Tron"

 Ed Dillinger (3):
       Renomeie o programa de xadrez para "MCP"
       Modificar programa de xadrez
       Atualizar programa de xadrez

 Walter Gibbs (1):
       Introduzir programa de xadrez protoype

Existem muitas outras situações em que é necessário distinguir entre o cabeçalho e o corpo do commit - e, para isso, eles devem ser separados por uma linha vazia.

2. Limite o título a 50 caracteres

Tecnicamente, é possível ultrapassar 50 caracteres, mas não é recomendado. Esse tamanho do título garante sua legibilidade e também faz o autor pensar na redação mais concisa e clara para descrever o que está acontecendo.

Dica: se é difícil para você resumir os resultados do trabalho, talvez um commit contenha muitas alterações. Esforce-se para fazer confirmações atômicas (este é um tópico para uma postagem separada).

A interface do GitHub suporta claramente essas convenções. Ele avisará se você exceder o limite de 50 caracteres:


E corte todos os cabeçalhos com mais de 72 caracteres, substituindo uma elipse:


Portanto, mencione 50 caracteres, mas lembre-se de que 72 é uma restrição estrita.

3. Coloque em maiúscula o título

Tudo é simples aqui. Coloque em maiúscula todos os títulos.

Por exemplo:

• Acelere para 88 milhas por hora

Em vez disso:

• acelerar para 88 milhas por hora

4. Não coloque um ponto no final do título

Não há necessidade disso. Além disso, cada personagem conta quando tentamos encontrar 50.

Por exemplo:

• Abra as portas do compartimento

Em vez disso:

• Abra as portas do compartimento.

5. Use o imperativo no título.

O humor imperativo significa literalmente: uma forma de verbo que expressa uma vontade (ordem, pedido ou conselho). Alguns exemplos:

• Limpe seu quarto (arrume o quarto)
• Feche a porta
• Retire o lixo

Cada uma das sete regras sobre as quais você está lendo é escrita de modo imperativo ("Vá para a próxima linha do corpo com 72 caracteres" etc.).

Este formulário pode parecer um pouco rude e, portanto, não é tão frequentemente usado [em inglês - aprox. trans. ] Mas é perfeito para o cabeçalho de confirmação. Uma razão é o fato de o próprio Git usar o imperativo quando se compromete em seu nome.
Por exemplo, ao usar o git merge, a seguinte mensagem será adicionada por padrão:

 Mesclar ramo 'myfeature'

E ao usar o git revert :

 Reverter "Adicione a coisa com as coisas"
	
 Isso reverte a confirmação cc87791524aedd593cff5a74532befe7ab69ce9d.

Ou quando você clica no botão "Mesclar" na interface de solicitação de recebimento no GitHub:

 Mesclar solicitação de recebimento nº 123 de someuser / somebranch

Portanto, quando você escreve suas próprias mensagens de confirmação no modo imperativo, segue as regras estabelecidas no próprio Git. Por exemplo:

• Refatorar o subsistema X para facilitar a leitura
• Atualizar a documentação de introdução
• Remover métodos obsoletos
• Release version 1.0.0

Este método pode inicialmente parecer desconfortável. Estamos mais acostumados a usar indicativos, com maior probabilidade de relatar fatos. Portanto, as mensagens de confirmação geralmente se tornam algo como isto:

• Corrigido o erro com Y
• Mudando o comportamento de X

E, às vezes, os cabeçalhos simplesmente descrevem o conteúdo do commit:

• Mais correções para coisas quebradas
• Novos métodos API agradáveis

Existe uma regra simples que permitirá evitar erros.

Um cabeçalho de consolidação adequadamente composto deve concluir a seguinte frase:

• Se aplicado, esse commit < cabeçalho do commit >

Por exemplo:

• Se aplicado, esse commit refatorará o subsistema X para facilitar a leitura
• Se aplicado, esse commit atualizará a documentação de introdução
• Se aplicado, esse commit removerá métodos obsoletos
• Se aplicado, este commit lançará a versão 1.0.0

Se aplicado, esse commit mesclará a solicitação de recebimento nº 123 do usuário / filial

Certifique-se de que verbos em outros humores, não imperativos, não funcionem aqui:

• Se aplicado, esse commit corrigirá um erro com Y
• Se aplicado, esse commit alterará o comportamento de X
• Se aplicado, esse commit corrigirá mais as coisas quebradas
• Se aplicado, esse commit adicionará novos métodos de API

Lembre-se: usar o imperativo é importante apenas no cabeçalho do commit. No corpo do commit, isso é opcional.

6. Vá para a próxima linha do corpo com 72 caracteres

O próprio Git não organiza quebras de linha automaticamente. Ao editar o corpo do comentário, lembre-se da borda direita e defina quebras de linha manualmente.

É recomendável que você vá para a próxima linha com 72 caracteres, para que o Git possa recuar e ainda caber 80 caracteres no total.

Um bom editor de texto pode ajudar com isso. É muito fácil configurar, digamos, Vim, o feed de linha de 72 caracteres para escrever uma mensagem em uma confirmação. No entanto, aconteceu que os IDEs são péssimos em oferecer suporte a quebras de linha inteligentes para confirmação de mensagens (embora as últimas versões do IntelliJ IDEA finalmente tenham melhorado nesta parte). ( aprox. por. - talvez no momento tudo esteja muito melhor ).

7. No corpo, responda às perguntas “o quê” e “por que”, não “como”

Esta confirmação do repositório Bitcoin fornece uma excelente explicação sobre o que e por que mudou:

 confirmar eb0b56b19017ab5c16c745e6da39c53126924ed6
 Autor: Pieter Wuille <pieter.wuille@gmail.com>
 Data: Sex 1 de agosto 22:57:55 2014 +0200

    Simplifique o tratamento de exceções de serialize.h

    Remova o 'state' e 'exceptmask' do fluxo de serialize.h
    implementações, bem como métodos relacionados.

    Como a máscara de exceção sempre incluía 'failbit', e o setstate era sempre
    chamado com bits = failbit, tudo o que fez foi imediatamente levantar um
    exceção.  Livre-se dessas variáveis ​​e substitua o setstate
    com exceção direta de lançamento (que também remove alguns mortos
    código).

    Como resultado, good () nunca é alcançado após uma falha (existem
    apenas 2 chamadas, uma das quais está em testes) e pode ser substituída
    por! eof ().

    fail (), clear (n) e exceções () nunca são chamadas.  Excluir
    eles.

Observe as alterações no código e pense em quanto tempo o autor economizou para os participantes atuais e futuros do projeto, descrevendo o contexto do trabalho realizado no comentário. Caso contrário, ele provavelmente estaria perdido para sempre.

Na maioria dos casos, você pode omitir os detalhes de como as alterações foram feitas. Normalmente, o código fala por si nesse sentido (e se é tão complexo que é necessário esclarecer, há comentários para ele).

Concentre-se principalmente em explicar por que as mudanças foram feitas - descreva a situação antes da mudança (e o que havia de errado), a situação depois e por que você escolheu essa maneira específica de resolver o problema.

Talvez no futuro você se agradeça por isso!

Dicas

Ame a linha de comando. Esquecido sobre o IDE.

Existem muitas razões - pelo número de comandos do Git - para usar a linha de comando ao máximo. Git é uma ferramenta incrivelmente poderosa; IDE - também, mas cada um à sua maneira. Eu uso o IntelliJ IDEA todos os dias, muitas vezes tive que lidar com outras pessoas (por exemplo, Eclipse), mas nunca vi que a integração do Git no IDE pudesse ser comparada em simplicidade e recursos à linha de comando (assim que você o entender).

Certos recursos do IDE para controle de versão são simplesmente inestimáveis, por exemplo, executando automaticamente o git rm ao excluir um arquivo ou outras partes necessárias do git ao renomeá-lo. Mas é muito pior quando você tenta confirmar, mesclar, refazer a análise ou fazer análises complexas do histórico de confirmações usando o IDE.

Quando você precisa desbloquear todo o potencial do Git, a linha de comando é inigualável.
Lembre-se de que, se você usa Bash, Zsh ou Powershell - existem scripts para concluir comandos que o salvam da dolorosa necessidade de lembrar de todos os subcomandos e opções.

Leia o livro Pro Git

O magnífico livro Pro Git ( também em russo - aprox. Transl. ) Está disponível gratuitamente. Aproveite isso!