Toda linha de código é documentada

A qualidade do seu código é muito importante! Mas, se você quiser melhorar a qualidade do seu trabalho, tente escrever mensagens de commit melhores.

Quem escreveu a linha 4 do trecho de código abaixo decidiu acessar a propriedade clientLeft de um nó do DOM por alguma razão, mas não fez nada com o resultado. Isso é um tanto misterioso.

Você consegue descobrir por que ele fez isso? Seria seguro remover ou alterar o código no futuro?

1 // ...
2 if (duration > 0) this.bind(endEvent, wrappedCallback)
3
4 this.get(0).clientLeft
5
6 this.css(cssValues)

Se alguém te mostrasse este código, como eu fiz aqui, você provavelmente não teria condições de dizer quem escreveu esta linha, quais foram seus motivos ou se seria necessário mantê-la no futuro.

No entanto, na maior parte do tempo em que você estiver trabalhando em algum projeto, você terá acesso ao histórico do VCS (Version Control System; no nosso caso, o GIT).

O histórico do projeto é sua documentação mais valiosa

O mistério acaba quando nós verificamos a mensagem do commit que inseriu a linha:

$ git show $(git blame example.js -L 4,4 | awk '{print $1}')
Conserta animate() para novos elementos inseridos no DOM

Ativar transições CSS para novos elementos inseridos no DOM não funciona no Webkit ou Firefox. Para que funcionasse, costumávamos atrasar a definição do CSS usando um setTimeout (ver #272513b).

Isso resolvia o problema para o Webkit, mas não para as últimas versões do Firefox; este parece precisar de, pelo menos, um atraso de 15ms; e mesmo este número varia.

Uma solução melhor para ambas engines é disparar “layout”. Isso é feito aqui ao ler a propriedade `clientLeft` do elemento. Existem outras propriedade e métodos que disparam “layout”.
Veja em: http://gent.ilcore.com/2011/03/how-not-to-trigger-layout-in-webkit.html

Como podemos ver, esta linha — ou, no caso, a alteração que inseriu esta linha — está muito bem documentada, com informações como: por que ela é necessária, por que a abordagem anterior não funcionava e quais navegadores são afetados e até um link de referência para quem quiser saber mais sobre a solução!

O código em si sempre poderia ser melhor:
A solução poderia ter sido encapsulada em uma função com um nome mais expressivo (como triggerLayout()) ou, ao menos, poderia ter um comentário explicando o porquê da linha. Mas… code happens!

Mesmo se o código fosse mais expressivo ou se tivesse linhas de comentário, o histórico do projeto poderia prover mais informações, como:

  1. Quem inseriu o código;
  2. Quando o código foi inserido;
  3. Quais são os testes necessários;
  4. A história completa do commit, mesmo quando os comentários são sucintos.

Esteja do lado certo do histórico

Tenha sempre em mente que, o que você está fazendo hoje, irá entrar para o histórico do projeto e vai ficar lá para sempre! Para ser legal com quem trabalha com você (isso inclui você mesmo em 3 meses), siga essas regras básicas quando fizer um commit:

Sempre escreva um commit como se você estivesse explicando a alteração para um colega ao seu lado, mas que não tem ideia do que está acontecendo.

Tente responder estas perguntas:

  1. Por que isso é necessário?
  2. Como isso resolve o problema?
  3. Quais são os efeitos colaterais da alteração?

Sempre limpe seus commits antes de fazer um push

Se os commits ainda não foram compartilhados, considere fazer um rebase para verificar e limpar as mensagens de commit do seu bloco de trabalho.

Para isso, utilize o rebase interativo e siga as instruções na tela.

git rebase -i remote/branch

Evite alterações não-relacionadas

Você pode ter encontrado uma correção de texto ou fez uma pequena refatoração no mesmo arquivo no qual você está trabalhando, mas resista à tentação de registrá-los ao mesmo tempo que as alterações principais, a não ser que sejam diretamente relacionadas.

Além disso, toda linha de código de um commit deve ter um propósito. Existem formas inteligentes de programar para assegurar de que uma linha não precise ser alterada como efeito colateral.

Por exemplo:

$fruits = [ 'banana', 'apple', 'grape' ];

Na linha de código anterior, é impossível alterar um dos itens sem alterar a linha toda.
Uma abordagem melhor seria:

$fruits = [
    'banana',
    'apple',
    'grape',
];

Além de separar a lista em várias linhas, preste atenção na vírgula após o último item.
Desta forma, podemos remover ou inserir um item na lista em qualquer posição sem precisar alterar nenhum outro item por acidente.

Leitura adicional

Este artigo é uma adaptação para o português de Every line of code is always documented, por Mislav Marohnić.

Para quem quer se aprofundar mais no assunto, no artigo original, ele apresenta alguns comandos para encontrar e exibir mensagens de commit, que serão traduzidos/adaptados por aqui no futuro.

Outro artigo com boas dicas sobre como fazer bons commits é o 5 Useful Tips For A Better Commit Message.

Caso você trabalhe com ferramentas open-source específicas, pesquise suas regras de colaboração (como a do Symfony, por exemplo). Geralmente estas documentações têm dicas bacanas e específicas sobre como organizar os seu código e seus commits.