CLs pequenos e simples são:
Observe que os revisores têm a discrição de rejeitar sua alteração totalmente pelo simples motivo de ser muito grande. Geralmente, eles vão agradecer pela sua contribuição, mas solicitar que você a divida em uma série de alterações menores. Pode dar muito trabalho dividir uma alteração depois de já tê-la escrito, ou pode exigir muito tempo argumentar sobre por que o revisor deveria aceitar sua grande alteração. É mais fácil escrever CLs pequenos desde o início.
Em geral, o tamanho certo para uma CL é uma alteração autocontida. Isso significa que:
Não há regras rígidas e rápidas sobre o tamanho “muito grande”. 100 linhas geralmente é um tamanho razoável para uma CL, e 1000 linhas geralmente é muito grande, mas isso fica a critério do seu revisor. O número de arquivos que uma alteração abrange também afeta seu “tamanho”. Uma alteração de 200 linhas em um arquivo pode ser aceitável, mas distribuída em 50 arquivos, geralmente será muito grande.
Lembre-se de que, embora você esteja intimamente envolvido com seu código desde o momento em que começou a escrevê-lo, o revisor geralmente não tem contexto. O que parece uma CL de tamanho aceitável para você pode ser esmagador para o revisor. Quando estiver em dúvida, escreva CLs menores do que você acredita ser necessário. Revisores raramente reclamam de receber CLs que são muito pequenas.
Existem algumas situações em que mudanças grandes não são tão ruins:
Outra maneira de dividir uma CL é por grupos de arquivos que exigirão revisores diferentes, mas que são alterações autocontidas.
Por exemplo: você envia uma CL para modificações em um protocolo de buffer e outra CL para alterações no código que usa esse protótipo. Você precisa enviar a CL do protótipo antes da CL do código, mas ambas podem ser revisadas simultaneamente. Se você fizer isso, talvez queira informar a ambos os grupos de revisores sobre a outra CL que você escreveu, para que eles tenham contexto para suas alterações.
Outro exemplo: você envia uma CL para uma alteração de código e outra para a configuração ou experimento que usa esse código; isso é mais fácil de reverter também, se necessário, já que arquivos de configuração/experimento são às vezes enviados para a produção mais rapidamente do que as alterações de código.
Geralmente, é melhor fazer refatorações em uma CL separada das alterações de recursos ou correções de bugs. Por exemplo, mover e renomear uma classe deve estar em uma CL diferente da correção de um bug nessa classe. É muito mais fácil para os revisores entenderem as alterações introduzidas por cada CL quando elas são separadas.
Pequenas limpezas, como corrigir o nome de uma variável local, podem ser incluídas dentro de uma CL de recurso ou correção de bug. Isso fica a critério dos desenvolvedores e revisores decidirem quando uma refatoração é tão grande que dificultará a revisão se incluída na sua CL atual.
CLs devem incluir código de teste relacionado. Lembre-se de que pequenez aqui se refere à ideia conceitual de que a CL deve ser focada e não é uma função simplista na contagem de linhas.
Uma CL que adiciona ou altera lógica deve ser acompanhada por testes novos ou atualizados para o novo comportamento. CLs de refatoração pura (que não têm a intenção de alterar o comportamento) também devem ser cobertas por testes; idealmente, esses testes já existem, mas se não existirem, você deve adicioná-los.
Modificações de teste independentes podem ser enviadas em CLs separados primeiro, assim como as diretrizes de refatoração. Isso inclui:
Se você tiver várias CLs que dependem umas das outras, precisará encontrar uma maneira de garantir que o sistema inteiro continue funcionando após cada submissão da CL. Caso contrário, você pode quebrar a compilação para todos os seus colegas desenvolvedores por alguns minutos entre as submissões das suas CLs (ou até mais tempo se algo der errado inesperadamente com suas submissões posteriores da CL).
Às vezes, você se deparará com situações em que parece que sua CL precisa ser grande. Isso é muito raro. Autores que praticam escrever CLs pequenos quase sempre conseguem encontrar uma maneira de decompor a funcionalidade em uma série de alterações pequenas.
Antes de escrever uma CL grande, considere se precedê-la com uma CL somente de refatoração pode abrir caminho para uma implementação mais limpa. Fale com seus colegas de equipe e veja se alguém tem ideias sobre como implementar a funcionalidade em CLs menores.
Se todas essas opções falharem (o que deve ser extremamente raro), obtenha consentimento de seus revisores antecipadamente para revisar uma CL grande, para que eles sejam avisados sobre o que está por vir. Nessa situação, espere passar muito tempo no processo de revisão, seja vigilante para não introduzir bugs e seja extra diligente na escrita de testes.