Melhores práticas de revisão de código

O autor beneficia da obtenção de uma perspetiva diferente da sua tarefa e código. É frequente aprenderem novos truques ou descobrirem uma forma potencialmente mais optimizada de resolver um determinado problema. Também implementarão o seu conjunto de alterações com confiança, sabendo que outras pessoas verificaram a correção do código e concordaram que está tudo bem.

O revisor beneficia de ver diferentes abordagens à resolução de problemas em ação. Também melhorarão as suas capacidades de leitura de código, o que é muito importante quando se mergulha, por exemplo, numa biblioteca que está a ser avaliada para utilização numa projeto. A revisão de código é também uma oportunidade de aprendizagem tanto para o revisor como para o autor: podem também aprender novos truques.

O equipa como um todo beneficia, uma vez que a análise de uma solução para um determinado problema exige a compreensão do problema, pelo menos a um nível elevado de abstração. Isto ajuda a eliminar quaisquer silos de conhecimento acidentais que possam existir numa equipa. Também aumentará o "fator autocarro": porque pelo menos duas pessoas (de preferência mais) estão cientes de uma determinada alteração, há menos probabilidade de uma situação em que ninguém na equipa sabe como atualizar um módulo, ou porque é que um determinado bug pode estar a ocorrer.

O cliente beneficia de alterações e soluções implementadas com rapidez e confiança. Juntamente com outras práticas recomendadas (como uma grande cobertura de testes, CI/CD, ambientes de teste, etc.), as revisões de código também garantem que o que é implementado é seguro, são e cumpre os requisitos conforme especificado.

Objetivo e utilização das presentes orientações

Lembre-se de que, acima de tudo, estas sugestões se destinam a criar um ambiente propício à resolução ambiciosa e eficiente de problemas, criando ao mesmo tempo uma rede de segurança e promovendo a confiança e a transparência em todos os membros da equipa.

Embora se sugira vivamente que uma equipa siga estas orientações, elas não pretendem ser regras rígidas e rápidas. Esta estrutura também não pretende ser um "processo" a ser seguido exatamente, uma vez que os processos rígidos tendem a diminuir a velocidade e a promover o desperdício.

É mais do que bem-vindo a desenvolver estas diretrizes na sua equipa. No entanto, lembre-se de que, à medida que os programadores alternam entre equipas, esperam que a revisão de código em qualquer equipa a que se juntem continue a basear-se neste documento. Mantenha quaisquer regras adicionais documentadas e contribua com melhorias que tenham funcionado excecionalmente bem para este documento.

Responsabilidades em matéria de revisão do código

Todos os membros da equipa têm determinadas responsabilidades no que diz respeito à revisão do código. A seguir, são apresentados alguns dos prós e contras da revisão de código por função no processo.

Chefe de projeto

• DO garantir que os seus repositórios estão bem configurados (por exemplo, não são permitidas fusões para o seu ramo virado para a produção sem pelo menos uma revisão de aprovação).
• DO assegure-se de que a sua equipa compreende e aplica estas práticas e trabalhe ativamente para promover a compreensão da razão pela qual fazemos as coisas de uma determinada forma.
• DO esteja atento a situações de empate, em que opiniões opostas não podem ser resolvidas: enquanto responsável técnico pela sua equipa, é da sua responsabilidade escolher a solução mais pertinente nesses casos e manter o trabalho em curso.
• No entanto, NÃO utilizar a liderança do projeto como um instrumento contundente. NÃO "puxar a fila". DO acolher a revisão e a crítica das suas soluções tanto quanto as encoraja no trabalho de qualquer pessoa.
• CONSIDERE adicionar uma integração do GitHub ao canal do Slack da sua equipa. Pode ser útil para colocar melhor os pedidos de revisão no radar dos revisores, mas dependendo do volume geral no seu canal, isto pode ou não ser adequado para a sua equipa.

Membro da equipa

• Participe nas revisões de código. Não é aceitável não rever o código.
• Lembre-se de fazer as suas revisões de código: os seus colegas de equipa dependem de si para progredir no seu trabalho!
• Se não puder de todo fazer uma determinada revisão, DO comunicá-lo de forma clara e aberta.
• No entanto, NÃO assumir que não pode fazer uma determinada revisão porque não conhece esse módulo/lado do sistema/especificação da lógica empresarial. A revisão de código é uma importante oportunidade de aprendizagem.
• Se achar que não sabe o suficiente sobre algo para fazer uma crítica, DO pergunte ao autor: ele terá todo o gosto em explicar o que é suposto as alterações fazerem.
• NÃO recusar críticas com base no nível de experiência (o seu ou do autor).
• DO tente rever pelo menos tantos PRs como os que produz. Idealmente, mantenha o rácio entre as revisões dadas e as revisões necessárias acima de 1 (especialmente em equipas maiores).

Autor

• DO compreender que é da sua responsabilidade ter o seu código revisto - a sua equipa pode estar proactivamente à procura de pull requests para rever, mas não tem de o fazer.
• NÃO atribuir/solicitar sempre revisões aos mesmos membros da equipa - beneficiará mais de um conjunto variado de revisores (e, inversamente, um maior número de programadores beneficiará da revisão do seu código)
• NÃO excluir alguém da revisão com base na experiência. Os programadores juniores beneficiam da revisão do código. Os programadores seniores beneficiam da revisão do código. Tal como referido no prefácio deste documento, todos beneficia da revisão do código.
• CONSIDERAR utilizar um sistema aleatório para selecionar os seus revisores. Por exemplo, em Rubi, %w[colega de equipa1 colega de equipa2 colega de equipa3].sample pode fazer maravilhas.
• DO atribua pelo menos dois revisores aos seus pull requests, a menos que seja absolutamente impossível. Desta forma, mais pessoas beneficiam do processo (e com três pessoas é mais difícil chegar a um empate).
• DO seja responsivo em seus pull requests. Embora não deva quebrar o seu fluxo para responder neste instante a quaisquer comentários, certifique-se de que as suas respostas são atempadas - caso contrário, os seus PRs ficarão na revisão de código indefinidamente.
• DO ter uma atitude aberta. Parta sempre do princípio de que o revisor está a tentar ajudar com as melhores intenções. Explique a sua lógica, aborde os argumentos do revisor e responda às suas perguntas.
• DO ser educado. Os mal-entendidos acontecem, mas não precisam de se descontrolar e prejudicar o ambiente da equipa.
• DO seja honesto. Se acredita que esta é a melhor solução, diga-o e apresente os seus argumentos. Se ficar convencido de que as sugestões do seu revisor são melhores do que as que produziu, diga-lhes. Se acha que pode ser produzida uma solução "melhor dos dois mundos" utilizando as suas ideias e as do seu revisor, proponha-lha. Em última análise, trabalhe para chegar a um consenso nos seus pull requests.
• DO deixe a resolução dos comentários para o seu revisor - não os resolva apenas porque está convencido de que já está tudo bem.
• DO explique ativamente a sua tarefa, o seu raciocínio e outros requisitos aos seus revisores. Não há problema em não saber, mas não é aceitável não saber.
• NÃO assumir que sabe tudo - todos nós somos especialistas fantásticos, mas é importante trazer uma certa dose de humildade para trabalhar consigo.
• DO ser o primeiro revisor do seu código. Use um chapéu de revisor e analise o código cuidadosamente, tal como faria com a pessoa de quem não gosta muito. Identifique e elimine as coisas mais óbvias, como linhas vazias, quaisquer restos ou especificações em falta. Não salte nada - o mais provável é que seja apontado de qualquer forma. Não desperdice o tempo dos revisores!
• DO descrever minuciosamente o seu pull request. A descrição é boa quando o revisor não será surpreendido por nada ao ler o código. Lembre-se que ele não pode ler a sua mente. É por isso que é importante descrever coisas que não são óbvias, decisões-chave com a razão ou todas as novas classes e ficheiros.
• CONSIDERAR utilizando o modelo de pedido pull. Se utilizar o Github, adicione-o ao seu repositório em .github/pull_request_template.md. Encoraja todos os membros da equipa a descrever os seus pull requests. Também é muito mais fácil de escrever quando se tem o campo de descrição preenchido com um modelo. Aqui pode encontrar um modelo que usamos num dos nossos projectos https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO compreender que é da sua responsabilidade ter o seu revisão de código - a sua equipa pode estar a procurar proactivamente pull requests para rever, mas não tem de o fazer.
• NÃO atribuir/solicitar sempre revisões do mesmo revisores de código - beneficiará mais de um conjunto variado de revisores (e, inversamente, um maior número de programadores beneficiará da revisão do seu código)
• NÃO excluir alguém da revisão com base na experiência. Os programadores juniores beneficiam do desempenho revisões de código. Os programadores seniores beneficiam do desempenho revisões de código. Tal como referido no prefácio do presente documento, todos benefícios do desempenho revisões de código.

Revisor

• DO utilizar a linguagem da sugestão em vez da exigência. Em vez de dizer "Deveria melhorar a qualidade do código fazendo X em vez disso", diz "Já pensou em melhorar qualidade do código ao fazer X?"
• DO explicar as suas sugestões. "Penso que o X é melhor aqui porque ajuda na transferência de conhecimentos e melhorar a qualidade do código."
• Mesmo que a sua sugestão provenha de fontes objectivas (por exemplo estilo de código orientações), DO pedir ao autor para fazer algo em vez de lhe dizer para fazer algo. "Por favor, mantenha todos os widgets em conformidade com o nosso estilo de código guia - [link]"
• NÃO assumir que sabe tudo. "Segundo o meu entendimento, este widget nunca deve ser um frobnicate e, nestas condições, será - trata-se de uma exceção que necessita de um revisão de código?"
• DO utilizar uma linguagem inclusiva. "Penso que estaríamos melhor no futuro se construíssemos isto desta forma. O que é que acha disto melhor revisão do código sugestão?" e "Talvez devêssemos usar o X aqui para um revisão eficaz do código?"
• DO sejam rápidos a fazer o vosso revisões de código. Não deve quebrar o seu fluxo para as fazer, mas tente manter o ciclo apertado, se possível. Algumas pessoas gostam de os fazer no início ou no fim dos seus dias de trabalho, como "aquecimento" ou "arrefecimento".

Note-se que estas palavras-chave foram inseridas de forma a manter intactos o contexto e a coerência do texto. Se pretender inseri-las em sítios específicos, por favor especifique.