Me deparei com um documento com regras e recomendações sobre o processo de revisão de código na empresa. Decidi que essas informações úteis deveriam ser compartilhadas com o mundo exterior. Com a bênção do
autor, publico o trabalho.
A maioria dessas regras é de natureza consultiva e deve ser guiada principalmente pelo senso comum, e não pela observância cega.
Disposições Gerais
- No hh.ru, a revisão ocorre no formato de solicitação de recebimento no Github.
- As solicitações de revisão e recebimento são necessárias, mesmo que na estrutura da tarefa uma linha ou um caractere no código seja alterado.
- Cada tarefa deve ter pelo menos um revisor responsável, é indicado na tarefa como revisor e é responsável pelo código, como o autor. Não é proibido e incentivado a participar da revisão de outras pessoas.
- A responsabilidade de conduzir a tarefa através da revisão recai sobre o autor da tarefa.
- Quaisquer alterações após uma revisão, como revisões durante o teste, também devem ser visualizadas.
Objetivos da Revisão
- Disseminação de experiência e conhecimento entre desenvolvedores.
- Suporte ao princípio - as alterações não devem piorar o código existente, devem melhorá-lo.
- Correção de erros na lógica e erros relacionados à segurança, tratamento correto de exceções.
- Melhorando a qualidade do código, a capacidade de manutenção e a arquitetura do projeto.
- Melhorando a legibilidade do código.
- Melhorando a cobertura e os testes no nível certo.
- Melhorando a documentação.
- Conformidade das mudanças com os requisitos da tarefa.
- Prevenção de dívida técnica ou imposto técnico.
- O design cuidadoso da API, onde a API é qualquer módulo com uma interface externa. Por exemplo, que um recurso em um serviço tenha uma URL bem pensada, um formato JSON conveniente, códigos de resposta corretos em diferentes casos e assim por diante.
- O histórico correto de confirmações no Gita, com mensagens que refletem a essência da mensagem, sem confirmações temporárias.
Preparando para Revisão
- Antes de publicar uma solicitação pull, leia seu código 2-3 vezes: com uma alta probabilidade, você mesmo encontrará erros, o que economizará tempo para o revisor. Verifique se não há erros que possam ser detectados automaticamente - erros no estilo do código, testes eliminados. Verifique se o código não possui comentários temporários e o código de depuração e também verifique se o código corresponde aos guias de estilo aceitos.
- Se você criar uma solicitação de recebimento no processo de trabalho em uma tarefa, escreva “[WIP]” no cabeçalho e coloque uma marca de “trabalho em andamento”. Quando o trabalho terminar, remova as tags e informe-as em um comentário separado, para que as partes interessadas saibam que o código pode ser visualizado.
- Esteja preparado para mostrar ao revisor uma mini demo na tarefa.
- Dê pequenas porções de código para revisão. 200 a 300 linhas de mudança - o limite para uma revisão eficaz.
- Faça alterações independentes em confirmações separadas.
- Descrever confirmações com mensagens curtas e informativas.
- Faça a refatoração como uma confirmação separada, é mais fácil ver mudanças na lógica, a essência da tarefa.
- Formate o código como uma confirmação separada antes das principais alterações ou mesmo como uma solicitação pull separada.
- Não faça pequenas alterações. Por exemplo, adicionando quebras de linha em um arquivo no qual você não alterou mais nada.
- No título da solicitação de recebimento, descreva de forma breve e informativa a essência das alterações.
- Descreva o problema e a solução na solicitação de recebimento. Descreva soluções alternativas e por que a solução atual está selecionada. Se as alterações estiverem relacionadas à interface, anexe as capturas de tela "antes" e "depois".
- Na solicitação de recebimento, forneça um link para a tarefa e, na tarefa, um link para a solicitação de recebimento.
- Às vezes, é útil discutir a solução escolhida com o revisor antes de escrever o código. Isso ajudará a encontrar a melhor solução para o problema e a simplificar o processo de revisão.
Escolha do Revisor
- Atribua a tarefa da revisão a um especialista na área relevante.
- Se vários comandos funcionarem com algum código, é útil selecionar um revisor de outra equipe para espalhar conhecimento.
- O oficial de justiça pode não ser o revisor responsável, mas pode participar do processo de revisão.
- Não entregue todas as suas tarefas à revisão para as mesmas pessoas - solicite críticas a pessoas diferentes.
- Se o problema envolver um pedaço de código não trivial que uma determinada pessoa entenda, mostre as alterações, independentemente de quem é o revisor responsável. Lembre-se também de que cada repositório possui mantenedores, eles sabem mais sobre esse código e supervisionam o desenvolvimento.
- O restante do revisor é escolhido arbitrariamente, de comum acordo entre as partes. Use as recomendações no github com base na "culpa" do código afetado para ajudá-lo a escolher.
- Após selecionar um revisor, especifique-o como um Responsável na solicitação de recebimento. Uma lista de todas as solicitações de recebimento atribuídas a você.
Processo de Revisão, Geral
Refere-se ao autor do código e ao revisor.
- Todo o código é comum, não existem conceitos como "meu código" ou "seu código". Isso significa que todo desenvolvedor é responsável por qualquer linha de código, e não apenas quem escreveu essa linha.
- Crie uma atmosfera de entendimento mútuo, seja educado e amigável, valorize e respeite um ao outro, não imponha sua opinião. Ouça a opinião do oponente e não defenda seu princípio. Não transforme a revisão em uma experiência negativa para os colegas.
- Faça perguntas se algo não estiver claro. Argumentar e especificar perguntas e respostas. Pode não ser óbvio para o autor do código o que se quer dizer com a pergunta "por que isso acontece?", Mas o revisor não entende a argumentação da resposta "discordo".
- Não estique o processo de revisão, economize tempo, responda rapidamente a comentários, discuta verbalmente, não provoque longas discussões e não produza “holivares”. Se você não conseguir chegar rapidamente a um consenso, procure ajuda de seus colegas, mantenedor ou gerente da área funcional.
- Se a tarefa não estiver em algumas linhas, gaste de 10 a 15 minutos com o revisor em uma revisão de código conjunto, é útil fazer isso mesmo antes de criar uma solicitação de recebimento. Discuta a essência da tarefa e solução, veja como foi e se tornou em um ambiente de trabalho. Isso ajudará o revisor a mergulhar melhor no contexto da tarefa. A maioria dos comentários permanecerá não escrita, o que economizará tempo de todos.
- Após uma discussão oral, descreva sempre a decisão tomada e os motivos da solicitação. A responsabilidade pela descrição é do autor do código.
- Se o código contiver o mesmo tipo de erro, o revisor deve focar a atenção do autor do código no primeiro ou no segundo comentário, sem comentar em cada entrada, e o autor deve analisar o código para o mesmo tipo de erro antes de publicar a correção.
- Elogie as decisões bem-sucedidas do autor e as sugestões do revisor.
- Deixe comentários sobre as alterações na solicitação de recebimento propriamente dita e não sobre confirmações individuais. Assim, toda a correspondência estará em um só lugar, inclusive após o rebase.
- Responda a comentários nos mesmos tópicos de discussão em que começaram. Se o comentário se referir à solicitação pull inteira ou a vários comentários no mesmo encadeamento, cite o comentário comentado. Para alternar para um tópico de discussão desatualizado de uma carta, use o link no caminho / para / arquivo em vez de visualizá-lo no link do GitHub.
- Se, durante o processo de revisão, forem tomadas decisões importantes do ponto de vista dos padrões de codificação ou de outros acordos formalizados, o autor do código é obrigado a anotar essas decisões nos documentos relevantes.
- A revisão não é apenas sobre o código, mas sobre toda a tarefa. Não trate os requisitos da tarefa ou dos layouts como a verdade suprema - todos cometem erros e ninguém pode levar em consideração todas as nuances. Um novo visual e sugestões sensatas só beneficiarão o produto.
Processo de revisão por autor do código
- A tarefa não foi concluída até que ela passou na revisão, teste e lançamento no "prod".
- Responda a todos os comentários do revisor, não deixe os comentários sem resposta, independentemente de você os ter aceito ou não.
- Pense nas perguntas que surgem ou podem surgir durante a revisão. Talvez a seção de código esteja sem um comentário ou seja melhor escrever o código de forma mais explícita.
- Não corrija as confirmações existentes com um gend commit --amend; em vez disso, faça alterações como confirmações separadas, uma para cada correção. A correção de confirmações existentes complica muito o processo de revisão, pois é necessário examinar todo o código novamente.
- Depois de adicionar uma nova confirmação à solicitação pull, escreva em um comentário separado um resumo das alterações para que as partes interessadas estejam informadas. Isso se aplica às correções durante a revisão, bem como às correções durante o teste.
- Após a revisão, antes de enviar a tarefa para teste, reescreva o histórico de confirmações (git rebase --interactive), fazendo correções nas confirmações individuais e excluindo as confirmações temporárias. Confira a opção --autosquash para simplificar o processo.
Processo de revisão por revisor
- Se você estiver ocupado no momento da solicitação de revisão, informe-me exatamente quando iniciará a revisão.
- Não exija, mas sugira fazer alterações.
- Comente o código, não a pessoa que o escreveu.
- Você assume a responsabilidade pelo código escrito, aborda a revisão de acordo, mas isso não significa que o autor do código deve cumprir estritamente todos os seus requisitos. Lembre-se, muitas coisas podem ser feitas de maneiras diferentes.
- Siga os objetivos da revisão e sugira edições substantivas. Não insista em mudanças não críticas. Indique a importância das correções em um comentário.
- Se você encontrar um problema sério, faça uma pausa na revisão e aguarde o autor corrigi-la. Muito provavelmente, após a correção, ainda será necessário revisar novamente.
- Preste atenção não apenas ao que foi alterado, mas também ao que não foi alterado. Procure e mostre ao autor o código que deveria ter sido alterado, mas não foi (importações esquecidas ou classes não utilizadas, usando código refatorado em outro lugar etc.).
- Depois de fazer alterações pelo autor do código, revise as correções e revise toda a solicitação de recebimento novamente. Talvez, sujeito a correções, você tenha novos comentários ou perguntas.
- Não perca tempo revisando o código que não foi alterado como parte da tarefa. A alocação de uma parte do código em uma função é considerada uma alteração. A transferência de código "como está" não é considerada uma alteração. A reforma do código no arquivo afetado fica a critério do autor.
- O revisor não edita independentemente o código na ramificação, porque ele deseja tanto ou mais facilmente. As alterações são feitas pelo autor do código.
- Se você fez uma revisão, tente não atrasar ou alternar para outras tarefas em detrimento da atual
Materiais usados e links relacionados
PS Compartilhe suas regras, recomendações e casos úteis de usuários no processo de revisão nos comentários