Antes e depois das minhas mensagens de commit
Já queria produzir esse conteúdo há algum tempo, mas depois de dar um git log em alguns projetos meus antigos eu tomei um baita susto.
Nesse texto pretendo descrever dificuldades, motivações e dicas que me ajudaram a melhorar absurdamente minhas mensagens de commit. Ah, e é claro, vou mostrar minha evolução com exemplos — porque humilhação pública nunca é demais haha.
Como não vou falar tanto sobre convenções, recomendo de antemão esse material:
Imagine que as contribuições de código enviadas em um commit são uma foto que o Sistema de Controle de Versão tira dos seus arquivos naquele momento. Sendo assim, podemos considerar a mensagem como sendo a legenda da foto.
Mas mais do que isso, tome a mensagem como algo intrínseco ao seu trabalho, leve alguns minutos para escrever melhor e isso trará clareza e propósito às suas contribuições.
O que me atrapalha a escrever boas mensagens de commit
Vejam que eu escrevi “atrapalha” no presente.
Mesmo depois de consciente, acho que é mal de Dev se deixar levar por uma ou mais dessas questões:
- pressa para subir a alteração
Ahhh mas a release tem que sair agora.
Quem nunca?
- preguiça
Às vezes você pode pensar que está escrevendo algo trivial/redundante, afinal “todo mundo sabe o motivo pelo qual eu estou fazendo tal alteração” (e talvez todo mundo saiba mesmo, naquele momento). Pense sempre na atemporalidade da coisa. Talvez daqui a um mês você nem lembre mais o contexto daquele código.
Obs.: se está trivial a ponto de você explicar o que foi feito — aí temos um problema. Falarei disso mais na frente.
- falta de atomicidade
Criar commits salvadores da pátria/que fazem mil coisas atrapalha muito na hora de descrevê-los. Eu sei que às vezes, no âmbito de uma feature branch, por exemplo, você vai ter vários commits, e às vezes você já fez várias coisas sem commitar, e tem arquivo com modificação em enredos diferentes e etc… mas aí é aprender a usar o Git a seu favor (tem algumas magias aqui).
- imperícia (me lembrei das aulas da autoescola)
Eu realmente não sabia o quanto era importante escrever de uma forma mais adequada.
- imprudência
Aqui é quando você já sabe que é importante mas se deixa levar por um dos três primeiros motivos.
Ah mas eu trabalho só.
Escreva boas mensagens de commit.
Ah mas é só um teste para uma vaga.
Escreva boas mensagens de commit.
E pra justificar toda essa minha insistência…
Motivos para melhorar suas mensagens de commit
Gente, esses e outros motivos estão aos montes pela internet — só listei os que mais me chamam a atenção.
Como eu mesma levei muito tempo para entender de fato isso, vamos refletir com calma.
- traz mais contexto pra quem revisa o código
Revisão já é um troço trabalhoso. Vamos nos ajudar?
- te auxilia na hora de lembrar no que foi trabalhado
Tanto no âmbito de uma release, como quando como você consulta códigos legados ou apenas antigos projetos seus, por exemplo.
- passa organização e cuidado
Você não vai querer que o time, seu eu do futuro, ou pessoas que irão te avaliar pensem que você tem desmazelo com o código.
Exemplos reais
Escolhi alguns commits meus de cerca de 6 meses a 3 anos atrás, e descrevi como eu os escreveria hoje. Segue o resultado.
Vamos lá!
Antes
Existia um determinado tipo de usuário que não iria mais ver um determinado layout. Esse layout só era exibido pra esse tipo de usuário, ou seja, esse código foi removido nesse commit.
Depois
O antigo título me parece muito grande (no lugar de x e z existiam outras palavras). Eu escreveria de uma forma mais sucinta e explicaria com mais detalhes no corpo, talvez acrescentando alguma url de apoio.
Antes
Nesse commit, eu verificava uma flag vinda de uma requisição, e dependendo do valor dela eu exibia ou não a funcionalidade x, e exatamente o mesmo foi feito para a funcionalidade y. Obs.: a tal requisição já estava sendo feita antes, eu só pegava esse valor novo.
Depois
Primeiro ponto, hoje eu faria dois commits: um para exibir a funcionalidade x, caso o valor da flag permitisse, e o outro para fazer o mesmo para a funcionalidade y.
Segundo, acho que “flag de ativação”, além de usar um linguajar de desenvolvimento, soou estranho para o que realmente estava sendo submetido. Afinal, a funcionalidade estava ativada, ela só não estava sendo apresentada.
Antes
Não precisei ver os arquivos modificados pra entender do que se tratava a alteração, isso já foi um avanço. Basicamente, uma ação que era feita através de um dialog, passou a ser feita através de uma tela, em uma aplicação móvel.
Depois
Hoje, talvez eu reescrevesse em dois commits. Um para retirar o código do dialog, e o outro para escrever a tela nova. Veja bem, no corpo do commit eu não preciso escrever coisas como “Remove código do dialog de x”, pois isso é autoexplicativo no código, mas essa frase poderia fazer sentido no título de um commit, por exemplo.
Sendo bem sincera? “Regras de negócio foram mantidas” não me diz muita coisa. Que regras são essas? Também adicionaria o link para a UI desenhada.
Antes
Resolvi ir mais a fundo e pegar commits de trabalhos da faculdade.
Esse foi um commit em que eu criei 8 arquivos, entre páginas HTML e estilos em CSS usando SASS, para um perfil de administrador de 4 entidades do sistema. Eu precisei dar um git show no commit pra entender o que eu tinha feito, pois só com o commit ficaria impossível deduzir.
Não sei traduzir em palavras o que estou sentindo agora. Eu pensava que commit era igual escrever código, no sentido de não usar til e acentos. Não começava o título com letra maiúscula. Nunca escrevia commits com corpo. Não sabia enviar com uma atomicidade que fizesse sentido.
Depois
cação, concedemos ao administrador a possibilidade de inserir/edi-
tar/excluir x. Zeplin-Url: <insira_a_url_aqui>”.
Provavelmente eu quebraria esse commit em 4, um para cada entidade envolvida. Adicionaria links com os arquivos de design desenhados no corpo, e uma descrição explicando como a alteração agrega ao contexto e quaisquer possíveis limitações (como porque tomei alguma decisão ou explicando que ainda estava faltando tal interação por conta de alguma conversa entre o time e etc).
Antes
Esse foi meu primeiro envio da vida. Foi na matéria de Programação Web na faculdade. Acredito que o professor pediu que escrevêssemos dessa forma, então talvez não faça tanto sentido ilustrá-lo aqui. Mas mesmo assim achei válido por demonstrar as mudanças na minha visão e uso de um VCS. Lembro de ter achado fantástico esse negócio e me senti a hacker por ter criado um repositório e feito um envio. Cada envio era um exercício que o professor avaliava (acho que ele não avaliava a mensagem, só os arquivos). Esse commit em específico era um HTML simples com alguns títulos, links, tabelas e inputs.
Depois
Acho que a essa altura você já deve ter entendido meu modelo mental pra escrever commits. A questão é praticar.
Compilado de segredos
Seguem algumas características que ajudam a melhorar as mensagens, ressaltando desde já que não acredito em nada escrito em pedra — a definição do time é maior do que qualquer convenção da literatura.
- adote um padrão
Por exemplo, se você/o time escreve as mensagens em inglês, acho válido manter dessa forma (a não ser que por algum motivo vocês decidam adotar o português posteriormente). Pode passar desorganização escrever alguns commits em inglês e outros em português.
Outro exemplo é o seguinte: existe uma convenção que nos diz para escrever o título usando o verbo no modo imperativo, como se fosse uma ordem. Eu, particularmente, gosto muito de escrever dessa forma, mas já vi gente que escreve no infinitivo, sem flexão de modo, e acho que está tudo bem. Nem tudo precisa ser seguido a risca. Apenas procure manter um padrão dentro do projeto.
- é principalmente sobre a motivação, e não sobre o que foi feito (o código já diz isso na maioria das vezes)
No corpo do commit, você não precisa escrever coisas como “Remove Classe x”, “Usa biblioteca y”, “Corrige null pointer exception” e assim por diante. Informações assim são visíveis no código e poderiam ser descritas como “Classe x não estava sendo utilizada”, “Optei por usar a biblioteca y por causa de a e b vantagens em relação a biblioteca h”, “O problema acontecia quando o usuário tomava tal ação e blá blá blá”.
Às vezes, você não vai precisar de um commit com corpo, apenas com título. Alguns exemplos de títulos nesse sentido seriam “Remove classe não utilizada b”, “Converte classe y para a linguagem z” (caso você não tenha usado algum recurso da linguagem que ache válido explicar), “Corrige erro no texto b” e assim por diante.
Isso, é treino.
- é pro CEO (estou considerando que essa pessoa não é técnica) da empresa entender — a abstração é a nível de negócio
Isso vale principalmente pro título, o corpo pode até conter decisões técnicas, mas em alto nível. Esse ponto até hoje é um pouco confuso pra mim, eu não entendia que palavras como “crash”, “class”, “method” e “subscribe” tem espaço no body. Você pode por exemplo descrever decisões arquiteturais.
Outras coisas que ajudam
- “taggear” os commits
- linkar os commits com urls com materiais de auxílio para entendimento do que foi feito (SDKs de eventos, estórias, UI e etc)
- ter pessoas críticas revisando suas mensagens — nada melhor do que aprender com puxões de orelha!
Espero que o texto tenha ajudado :)
Caso possua dúvidas ou algo a acrescentar, fique à vontade nos comentários.
Siga a tag codelikeagirlBR para ver nossos posts! :D
Quer escrever ou traduzir artigos em português para a Code Like A Girl? Se você já faz parte do time de escritoras(es) da Code Like A Girl basta enviar seu artigo diretamente para nossa publicação. Se você ainda não faz parte do nosso time, envie uma mensagem direta para a conta de twitter CodeLikeAGirlBr. Nós avaliaremos seu artigo e ajudaremos a refiná-lo para publicação.
