Como fazer o inspetor de código amar você





Quando se trata de inspeção de código, as pessoas tendem a se concentrar em quem está fazendo isso. Mas o desenvolvedor que escreveu o código desempenha um papel tão importante no processo quanto o revisor. Quase não há recomendações para preparar o código para inspeção, então os autores freqüentemente cometem erros simplesmente por ignorância.



Este artigo compila as práticas recomendadas para participar da inspeção de código como autor. Quando terminar de ler, você começará a enviar aos inspetores conjuntos de mudanças tão perfeitos que eles vão queimar de amor por você, nada menos.



Mas não quero que os inspetores de código brilhem de amor por mim



E eles ainda serão. Humilha-te. Ninguém na história da humanidade ainda reclamou em seu leito de morte que ele foi muito amado durante sua vida.



Por que melhorar a inspeção de código?



Aprender técnicas de inspeção eficazes facilitará a vida do inspetor, da equipe e, o mais importante, de você.



  • Processo de transferência de conhecimento acelerado. Se você preparar seu conjunto de mudanças adequadamente, a atenção do inspetor será direcionada para as áreas nas quais você precisa crescer, ao invés de falhas estilísticas enfadonhas. E quando você deixa claro que valoriza a crítica construtiva, o revisor começa a se esforçar mais no feedback.
  • Um exemplo para outros. Boas práticas de inspeção de código em sua execução definirão o padrão para aqueles ao seu redor. Boas técnicas geralmente são adotadas, o que significa que será mais fácil para você quando um colega enviar o código para revisão.
  • Conflitos mínimos. A inspeção do código geralmente cria tensão na equipe. Se você abordar os negócios de forma responsável e deliberada, as disputas surgirão com menos frequência.


Regra de ouro: valorize o tempo do revisor



Isso parece óbvio, mas frequentemente encontro autores que tratam os inspetores como seus especialistas em controle de qualidade pessoal. Essas pessoas não tocarão um dedo para detectar pelo menos alguns dos erros ou para fazer um conjunto de alterações conveniente para verificação.



Seus colegas vêm trabalhar todos os dias com um suprimento limitado de atenção. Se eles dedicarem parte dele a você, não poderão mais gastar esse recurso em suas próprias tarefas. Aproveitar ao máximo seu tempo é uma questão de simples justiça.



A revisão do código é muito mais bem-sucedida quando os participantes podem confiar uns nos outros. Seu inspetor não poupará esforços se souber que você levará seus comentários a sério. Se você perceber o examinador como um obstáculo a ser superado, receberá recomendações muito menos valiosas dele.



Técnica



1. Revise o código



primeiro Antes de enviar o código a um colega, leia-o. Não se limite a detectar erros - imagine ver este fragmento pela primeira vez. O que pode ser confuso nisso?



Na minha experiência, pode ser útil fazer uma pausa entre escrever e editar o código. Muitas vezes, as pessoas enviam um novo trecho de código no final do dia, mas é durante esse período que é mais provável que percam algo por negligência. Espere até de manhã, dê uma nova olhada no conjunto de alterações e, em seguida, passe-o para um colega.







Que idiota escreveu isso?

Sincronizando Cron Jobs com o ciclo lunar: Eu adicionei lógica sincronizada para manter nosso




pipeline ETL em sintonia com a natureza Simule o ambiente de trabalho de um validador tanto quanto possível. Use o mesmo utilitário de comparação que ele. Erros estúpidos são mais bem encontrados nesses utilitários do que em seu editor de código regular.



Não espere ser perfeito. Você inevitavelmente enviará o código com uma parte que se esqueceu de excluir após corrigir um bug, ou um arquivo perdido que você iria remover. Não é o fim do mundo, mas ainda vale a pena acompanhar. Observe padrões em seus erros e descubra quais sistemas você pode implementar para evitá-los. Se os mesmos erros ocorrerem com frequência, o inspetor concluirá que você não valoriza o tempo dele.



2. Escreva uma descrição clara do changeset



Em meu último trabalho de mentor, tive reuniões ocasionais com um programador mais experiente. Antes da primeira reunião, ele me pediu para pegar um documento de design de software que eu havia compilado. Ao entregar os papéis a ele, expliquei o que era o projeto e como ele se relaciona com os objetivos da minha equipe. Meu mentor franziu a testa e disse sem rodeios: "Tudo o que você acabou de dizer deve estar na primeira página do documento."



E ele estava certo. Escrevi o documento com a expectativa de desenvolvedores da minha equipe, mas não levei em consideração que poderia ser lido por terceiros. O público não se limitou aos limites do meu departamento - ainda havia equipes de parceiros, mentores, pessoas que tomavam decisões sobre promoções... O documento deveria ter sido escrito de forma que tudo ficasse claro para eles. Após essa conversa, procuro sempre apresentar meu trabalho no contexto necessário para a compreensão.



A descrição do changeset deve incluir qualquer informação de fundo que o leitor possa precisar. Mesmo se você estiver escrevendo uma descrição para o revisor, lembre-se de que ele pode ter menos informações contextuais do que você pensa. Além disso, é possível que outros colegas também tenham que trabalhar com este código no futuro - ao visualizar o histórico de alterações, eles devem entender suas intenções.



Uma boa descrição descreve para que serve o changeset e por que você escolheu agir dessa forma.



Se você quiser se aprofundar na arte de escrever ótimas descrições, leia “ Como escrever uma mensagem de commit no Git ”, de Chris Beams, e “ Meu commit favorito no Git ”, de David Thompson.



3. Automatize coisas simples



Se você confia no inspetor para pequenas coisas como uma chave flutuante ou problemas com testes automatizados, então você está perdendo seu tempo.







Verifique se está tudo em ordem com a sintaxe? Eu recorreria ao compilador, mas é uma pena perder seu tempo.



Os testes automatizados devem ser considerados parte do procedimento padrão como parte da equipe. A inspeção começa apenas quando toda a série de verificações automatizadas em um ambiente de integração contínua é aprovada .



Se sua equipe está tragicamente delirante e rejeita a integração contínua, configure um check-out automatizado internamente. Implemente ganchos , linters e formatadores de pré-confirmação em seu ambiente de desenvolvimento para garantir que todas as convenções sejam seguidas e que o comportamento pretendido persista de confirmação para confirmação.



4. Certifique-se de que o próprio código responde às perguntas



O que está errado com esta imagem?







Não entendo o propósito da função.

E, isso é no caso de o Frombobulator ser passado ao chamar na ausência de implementação frombobulate. O




autor me ajudou a descobrir a função, mas e o próximo leitor? Investigando a história das mudanças e relendo todas as discussões? É ainda pior quando o autor vem à minha mesa para explicar tudo pessoalmente. Em primeiro lugar, impede-me de me concentrar e, em segundo lugar, nenhuma alma vivente terá mais acesso às informações que soam.



Quando um inspetor expressa confusão sobre um ponto no código, seu trabalho não é esclarecer a situação para aquela pessoa em particular. É necessário esclarecer a situação para todos de uma vez.







- Olá?

- Quando você escreveu bill.py há seis anos, por que tinha t = 6?

- Que bom que você ligou! Isso se deve ao imposto sobre vendas de 6%.

- Claro!

- Uma ótima maneira de justificar uma decisão de implementação.




A melhor resposta para qualquer pergunta é a refatoração de código que o remove. O que pode ser renomeado para tornar mais claro como alterar a lógica? Os comentários são uma solução aceitável, mas definitivamente atuam no contexto do código que se documenta naturalmente.



5. Insira as alterações fracionadas



Limites extensos são uma prática ruim e muitas vezes podem ser vistos ao inspecionar o código. O desenvolvedor se compromete a consertar um bug na lógica, mas ao longo do caminho encontra alguma falha na interface. "Bem, já que estou trabalhando com esta peça de qualquer maneira", ele pensa, "vou consertar ao mesmo tempo." Como resultado, começa a confusão. O revisor agora terá que descobrir quais alterações funcionam para a tarefa A e quais funcionam para a tarefa B.



Os melhores changesets fazem uma coisa . Quanto mais precisa e simples for a mudança, mais fácil será para o inspetor manter o contexto em mente. Ao compartilhar alterações não relacionadas, você também pode ter a capacidade de revisão de vários colegas em paralelo, para que o código retorne para você mais rápido.



6. Separe as



alterações funcionais e não funcionais Outra regra segue da restrição de dimensionamento - alterações funcionais e não funcionais não devem ser misturadas.



Os desenvolvedores com pouca experiência com inspeção de código geralmente quebram essa regra. Eles fazem algum tipo de alteração de detalhamento e o editor de código altera imediatamente o formato em todo o arquivo. O desenvolvedor não entende o que aconteceu, ou decide que é ainda melhor, e envia o código, onde uma mudança funcional está enterrada sob centenas de linhas com outras não funcionais.







Você encontrará uma mudança funcional?



Essa confusão é como uma saliva na cara de um inspetor. As alterações apenas de formato são fáceis de verificar. Mudanças funcionais também. Um colapso funcional em um oceano de mudanças de formato pode ser desperdiçado e louco.



Além disso, os desenvolvedores adoram combinar a refatoração com mudanças importantes em tempo hábil. Eu aprovo fortemente a refatoração de código por parte dos colegas, mas não quando eles implementam simultaneamente um novo comportamento.







Mudança comportamental enterrada no meio da refatoração



Se um trecho de código precisa de refatoração e mudanças de comportamento, você precisa dividir o processo em dois ou três conjuntos:



  1. Adicione testes para o comportamento atual (se não houver nenhum)
  2. Refatore o código sem alterar nada nos testes


Ao manter os testes intactos na segunda etapa, o revisor pode garantir que a refatoração não interrompa o comportamento. Conseqüentemente, no terceiro estágio, ele não terá que descobrir o que está refatorando aqui e o que funciona para mudar o comportamento - afinal, você separou um do outro com antecedência.



7. Divida os changesets que são muito grandes Os



changesets inchados são como os primos feios de limites extensos . Imagine uma situação: um desenvolvedor chega à conclusão de que, para implementar a funcionalidade A, ele primeiro terá que corrigir a semântica das bibliotecas B e C. Se houver poucas mudanças, não importa o que aconteça, mas muitas vezes essas modificações se espalham e uma lista enorme de mudanças é produzida.



A complexidade do changelog cresce exponencialmente com o número de linhas afetadas. Se as alterações afetarem 400 ou mais linhas, procuro uma maneira de fragmentá-las antes de solicitar uma inspeção.



Talvez em vez de fazer tudo de uma vez, seja possível trabalhar primeiro com as dependências e, no próximo conjunto, implementar uma nova funcionalidade? É realista manter o código são se você implementar metade da funcionalidade agora e a outra metade na próxima fase?



Pensar em como quebrar o código para obter uma parte funcional e inteligível pode ser entediante. Mas isso permite um melhor feedback e cria menos complexidade para o revisor.



8. Aceite as críticas com gentileza



A maneira mais segura de estragar todo o teste é aceitar as críticas com hostilidade. Pode ser difícil resistir, porque muitos desenvolvedores têm orgulho do que fazem e percebem seu trabalho como uma extensão de si mesmos. E se o inspetor fizer comentários sem tato ou for até uma pessoa , isso complica ainda mais o assunto.



Em última análise, você, como autor, é livre para decidir como responderá aos comentários. Trate as palavras do inspetor como uma discussão objetiva do código que nada tem a ver com a avaliação de sua personalidade. Se você ficar na defensiva, só vai piorar.



Tento interpretar quaisquer comentários como uma tentativa de ajudar e beneficiar. Se o revisor encontrar um erro estúpido no código, sou instintivamente atraído para começar a dar desculpas. Mas eu me contenho e elogio sua observação.







- Para janeiro e fevereiro de 1900, não funcionará.

- Exatamente, bem notado!




Curiosamente, o fato de o inspetor detectar falhas não óbvias no código é um bom sinal. Isso sugere que você é bom em preparar arquivos para digitalização. Na ausência de formatação desleixada, palavrões e outras coisas conspícuas, o revisor pode estudar a lógica e projetar profundamente e fazer observações mais valiosas.



9. Seja paciente se o inspetor cometer um erro



De vez em quando, acontece que o inspetor simplesmente se engana. Ele pode interpretar mal um código perfeitamente normal, assim como você pode plantar bugs. Muitos desenvolvedores em tais casos começam a se defender ferozmente. Eles se ofendem por alguém estar submetendo seu trabalho a críticas, mesmo não baseadas em nada.



No entanto, mesmo que o revisor esteja errado, você ainda tem muito em que pensar. Se ele interpretou algo errado, qual é a probabilidade de outras pessoas cometerem o mesmo erro no futuro? Os leitores não teriam que estudar o código para frente e para trás, apenas para se certificar de que o bug que eles veem não está aqui?







- Há um estouro de buffer aqui, porque nenhuma verificação foi realizada se há memória suficiente no nome para acomodar todos os caracteres NewNameLen.

- Está no meu código? Impensável! O construtor chama PurchaseHats e chama CheckWeather, que geraria um erro se o comprimento do buffer não fosse compatível. Você primeiro leria 200.000 linhas de código e então ousaria admitir a possibilidade de que eu estava errado em algum lugar.




Pense em como refatorar ou adicionar comentários para que, à primeira vista, você possa entender que tudo está em ordem aqui. Se o mal-entendido deriva do uso de recursos pouco conhecidos da linguagem, reescreva o código usando mecanismos que não requeiram conhecimento profundo.



10. Dê uma reação inteligível



Muitas vezes me encontro nesta situação: mando comentários para uma pessoa, ela atualiza o código levando em consideração alguns deles, mas ao mesmo tempo fica em silêncio. Existe um período de incerteza. Ou ele perdeu o resto dos comentários ou ainda está em processo de correção. Se você começar a verificar o que já foi feito, hipoteticamente, pode acontecer que esse trecho de código ainda esteja em funcionamento e eu esteja perdendo meu tempo. Se esperarmos, podemos entrar em um impasse - nós dois sentaremos e esperaremos o próximo passo um do outro.



Estabeleça uma determinada ordem de ações na equipe para que fique sempre claro quem está com o "bastão" no momento. Não se deve permitir que o processo diminua apenas porque ninguém entende o que está acontecendo. Isso é fácil de fazer - basta deixar comentários no nível do changeset, a partir do qual fica claro quando o direito de agir é transferido para outro participante.







Corrigindo os cabeçalhos> Atualizando o código de acordo com os comentários> Tudo está pronto, por favor, olhe.



Qualquer comentário que exija uma ação deve ser respondido, confirmando que você o executou. Algumas ferramentas de inspeção de código fornecem a capacidade de sinalizar comentários processados. Caso contrário, use um conjunto de marcadores de texto simples como Concluído. Se você discordar do comentário, explique educadamente por que decidiu não corrigir.







Algumas ferramentas, como Reviewable e Gerritt, sugerem marcar os comentários processados



. Equilibre suas reações com o esforço do revisor. Se ele detalhou um momento para que você aprenda algo novo por si mesmo, não se limite à marca “Feito”. Responda com atenção para mostrar que você valoriza o trabalho dele.



11. Solicite informações ausentes com habilidade



Às vezes, os comentários do inspetor deixam muito espaço para interpretação. Quando eles escrevem para você algo no espírito de "Não entendo esta função", surge imediatamente a pergunta: o que exatamente não está claro para uma pessoa. Demasiado longo? O nome é infeliz? Precisa documentar melhor?



Por muito tempo me perguntei como esclarecer comentários vagos e não entrar inadvertidamente em confronto. A primeira coisa que me veio à cabeça foi perguntar: “O que há de incompreensível nela?”, Mas soa mal-humorado.



Certa vez, enviei deliberadamente uma resposta vaga a esse tipo de colega, e ele me desarmou com sua resposta:



"O que pode ser alterado para torná-lo melhor?"


Gosto desta frase porque expressa abertura à crítica e falta de hostilidade. Agora, quando recebo um feedback vago, respondo com algumas variações do motivo básico "O que mudar para melhorar?"



Outra técnica útil é tentar adivinhar o que o revisor quis dizer e assumir a liderança na correção do código de acordo. Se você receber um comentário "incompreensível", dê uma olhada no código. Normalmente, é encontrado algo que pode ser melhorado em termos de clareza. As edições permitem que o inspetor saiba que você está pronto para fazer alterações, mesmo que ele tenha uma ideia diferente do resultado final.



12. Dê prioridade ao revisor



No tênis, se não estiver totalmente claro se a bola saiu da quadra ao sacar o adversário, é costume interpretar a situação a seu favor. Esta regra também deve ser seguida ao inspecionar seu código.



Algumas decisões de design são uma questão de gosto. Se o revisor achar que sua função de dez linhas seria melhor dividida em duas funções de cinco linhas, a verdade objetiva não é nem sua nem dele. Qual opção é melhor depende da preferência.



Se o inspetor fizer uma proposta e os argumentos em apoio à posição dele forem aproximadamente iguais para você, aceite o ponto de vista dele. Afinal, de vocês dois, ele é quem tira vantagem de uma nova olhada no código.



13. Reduza o tempo de transferência do código



Há alguns meses, um usuário fez uma pequena mudança em um projeto de código aberto que mantenho. Cancelei a assinatura com comentários algumas horas depois, mas ele já desapareceu com os fins. Alguns dias depois, voltei e descobri que ainda não havia resposta.



Seis semanas depois, o misterioso desenvolvedor reapareceu no projeto com revisões. Embora aprecie o seu trabalho, o longo intervalo entre as duas etapas de verificação levou ao fato de eu despender o dobro do esforço na inspeção. Tive que reler não apenas o código, mas também meus próprios comentários para lembrar o que foi discutido em geral. Se a pessoa aparecesse em alguns dias, não haveria necessidade de trabalho adicional.







Custos intelectuais para inspeção de código com tempos de transmissão curtos (esquerda) e longos (direita)

O eixo x é o tempo; eixo y - memória do inspetor; sombreamento azul - restauração de contexto; preenchimento azul - verificação de código; preenchimento cinza - esperando; sombreamento vermelho - custos adicionais




Seis semanas é, claro, um caso excepcional, mas frequentemente vejo longas pausas injustificadas em minha equipe. Alguém envia um conjunto de alterações para revisão, obtém feedback e adia as edições por uma semana porque estava distraído com outra tarefa.



Além do fato de que mais tarde você terá que gastar tempo recuperando o contexto, os fragmentos de código semiacabados criam complexidade. Eles tornam mais difícil acompanhar o que já foi drenado e o que ainda não foi. Quanto mais changelists parcialmente processados ​​forem criados, maior será a probabilidade de conflitos de fusão e ninguém gosta de mexer neles.



Depois de enviar seu código para inspeção, sua principal prioridade é seguir em frente. Se o processo para por sua culpa, você está roubando o tempo do inspetor e complicando a vida de toda a equipe.



Finalmente



Ao preparar seu próximo changelog para envio, considere quais fatores você pode abordar e usar essas oportunidades para tornar a revisão produtiva. Ao participar de uma revisão de código, verifique se há coisas que regularmente retardam o processo e desperdiçam recursos.



Lembre-se da regra de ouro: valorize o tempo do revisor. Se você der a ele a oportunidade de se concentrar nas partes realmente interessantes do código, seus comentários serão úteis. Se você o forçar a perder tempo com pequenas coisas ou desvendar a confusão, tanto pior para vocês dois.



Finalmente, pense cuidadosamente sobre suas respostas. Mal-entendidos sobre ninharias ou palavras impensadas podem atrapalhar as coisas com uma velocidade alarmante. As paixões são altas quando se trata de criticar o trabalho de outra pessoa, portanto, evite com cuidado qualquer coisa que possa levar o examinador a pensar que você o está atacando ou tratando com o devido respeito.



Parabéns! Se você leu até aqui, talvez já se considere um especialista em inspeção de código. Seus inspetores provavelmente já estão pegando fogo, então você os trata com humanidade.



All Articles