Visto fazer revisões diárias de código há mais de uma década. Os benefícios das revisões de código são muitos: alguém verifica o seu trabalho à procura de erros, aprende com a sua solução, e a colaboração ajuda a melhorar a abordagem geral da organização em matéria de ferramentas e automatização. Se não estiver actualmente a fazer revisões de código na sua organização, comece já. Isto fará de todos um melhor engenheiro.
Muitas pessoas e organizações partilharam as suas melhores práticas de revisão de código e o que a definição de boas revisões de código significa para eles. Os guias do Google, da equipa SmartBear, e do engenheiro Philipp Hauer são todos excelentes leituras. Abaixo está a minha opinião pessoal sobre o que são boas análises de código e como torná-las ainda melhores a nível de equipa e organizacional. Isto está no contexto do ambiente tecnológico em que tenho trabalhado – actualmente em Uber, e antes disso no Skype/Microsoft e Skyscanner.
As boas revisões de código são a barra pela qual todos nós devemos lutar. Abrangem as melhores práticas comuns e fáceis de seguir com as quais qualquer equipa pode começar, assegurando ao mesmo tempo revisões de alta qualidade e úteis a longo prazo.
As melhores revisões de código são onde os engenheiros continuam a melhorar a forma como fazem as revisões de código. Estas revisões de código analisam a mudança de código no contexto da base de códigos, de quem a está a solicitar e em que situação. Estas revisões ajustam a sua abordagem com base no contexto e na situação. O objectivo não é apenas ser uma revisão de alta qualidade, mas também ajudar os programadores e equipas que solicitam a revisão a serem mais produtivos.
Areas Covered by the Code Review
Good code reviews look at the change itself and how it fits into the codebase. Vão olhar através da clareza do título e descrição e “porquê” da alteração. Cobrem a correcção do código, cobertura de teste, alterações de funcionalidade, e confirmam que seguem os guias de codificação e as melhores práticas. Indicarão melhorias óbvias, tais como código de difícil compreensão, nomes pouco claros, código comentado, código não testado, ou casos de bordas desprotegidas. Observarão também quando demasiadas alterações estiverem comprimidas numa única revisão, e sugerirão manter as alterações de código com uma única finalidade ou quebrar a alteração em partes mais focalizadas.
As melhores revisões de código analisarão a alteração no contexto do sistema maior, bem como verificarão se as alterações são fáceis de manter. Podem fazer perguntas sobre a necessidade da mudança ou como esta tem impacto noutras partes do sistema. Analisam as abstracções introduzidas e como estas se enquadram na arquitectura de software existente. Observam observações de manutenção, tais como lógica complexa que poderia ser simplificada, melhoria da estrutura de testes, remoção de duplicações, e outras possíveis melhorias. O engenheiro Joel Kemp descreve as grandes revisões de código como um passe contextual após um passe inicial, leve.
Tom da Revisão
O tom das revisões de código pode influenciar grandemente a moral dentro das equipas. As revisões com um tom severo contribuem para a sensação de um ambiente hostil com as suas microagressões. A linguagem opinativa pode tornar as pessoas defensivas, desencadeando discussões acaloradas. Ao mesmo tempo, um tom profissional e positivo pode contribuir para um ambiente mais inclusivo. As pessoas nestes ambientes estão abertas a reacções construtivas e as revisões de código podem, em vez disso, desencadear discussões saudáveis e animadas.
As revisões de código de boas intenções fazem perguntas abertas em vez de fazer declarações fortes ou com opiniões fortes. Oferecem alternativas e possíveis soluções que podem funcionar melhor para a situação, sem insistir que essas soluções são a melhor ou única forma de proceder. Estas revisões assumem que ao revisor pode estar a faltar algo e pedem esclarecimento em vez de correcção.
As melhores revisões de código também são empáticas. Eles sabem que a pessoa que escreveu o código gastou muito tempo e esforço nesta mudança. Estas revisões de código são amáveis e despretensiosas. Aplaudem boas soluções e são globalmente positivas.
Aprovando vs Solicitando Alterações
Quando um revisor completa a sua revisão, pode ou marcá-la aprovada, bloquear a revisão com pedidos de alteração, ou não definir um estatuto específico, deixando-a num estado “ainda não aprovado”. A forma como os revisores utilizam os estados de aprovação e pedido de alterações é reveladora das revisões de código.
As boas revisões de código não aprovam alterações enquanto houver questões em aberto. No entanto, deixam claro quais as perguntas ou comentários que não são bloqueantes ou sem importância, marcando-as distintamente. São explícitas quando aprovam uma alteração – por exemplo, acrescentando um comentário de polegar para cima como “parece bom! Alguns lugares utilizam acrónimos como LGTM – estes também funcionam, mas saiba que os recém-chegados podem interpretar mal estes acrónimos de dentro para outra coisa. Boas revisões de código são igualmente explícitas quando pedem um seguimento, utilizando a ferramenta de revisão de código ou convenção de equipa para comunicar isto.
As melhores revisões de código são firmes no princípio mas flexíveis na prática: por vezes, certos comentários são abordados pelo autor com uma mudança de código separada e de seguimento. Para alterações mais urgentes do que outras, os revisores tentam disponibilizar-se para revisões mais rápidas.
From Code Reviews to Talk to Each Other
As revisões de código são geralmente feitas de forma assíncrona e por escrito através de uma ferramenta de revisão de código. Isto é normalmente por conveniência, para permitir revisões de código à distância, e para permitir que várias pessoas revejam a mesma alteração de código. Mas quando é a altura de parar de utilizar a ferramenta – seja ela boa – e começar a falar cara a cara sobre o código?
As boas revisões de código deixam tantos comentários e perguntas quantos forem necessários. Se a revisão não abordar todos eles, eles também os anotarão. Quando a conversa se prolongar por muito tempo, os revisores tentarão passar a falar pessoalmente com o autor, em vez de queimar mais tempo utilizando a ferramenta de revisão de código.
As melhores revisões de código alcançarão proactivamente a pessoa que faz a alteração depois de fazer uma primeira passagem sobre o código e terão muitos comentários e perguntas. Estas pessoas aprenderam que poupam muito tempo, mal-entendidos, e ressentimentos desta forma. O facto de haver muitos comentários sobre o código indica que é provável que haja algum mal-entendido de ambos os lados. Estes tipos de mal-entendidos são mais facilmente identificados e resolvidos através de comentários.
Nitpicks
Nitpicks são comentários sem importância, onde o código poderia ser fundido sem sequer os abordar. Poderiam ser coisas como declarações variáveis em ordem alfabética, testes unitários seguindo uma certa estrutura, ou parênteses na mesma linha.
As boas revisões de código tornam claro quando as alterações são insignificantes. Normalmente marcam comentários como estes de forma distinta, acrescentando-lhes o prefixo “nit:”. Muitos destes podem tornar-se frustrantes e desviar a atenção das partes mais importantes da revisão, pelo que os revisores pretendem não exagerar com estes.
As melhores revisões de código percebem que demasiados “nitpicks” são um sinal de falta de ferramentas ou de falta de normas. Os revisores que se depararem frequentemente com estes, procurarão resolver este problema fora do processo de revisão de códigos. Por exemplo, muitos dos comentários comuns dos “nitpick” podem ser resolvidos através da impressão automática. Os que normalmente não podem ser resolvidos pela equipa concordando com determinados padrões e seguindo-os – talvez até automatizando-os, eventualmente.
Code Reviews for New Joiners
Começar numa nova empresa é esmagador para a maioria das pessoas. A base de código é nova, o estilo de programação é diferente do que antes, e as pessoas revêem o seu código de forma muito diferente. Assim, as revisões de código devem ser mais suaves para os novos sócios, para os habituar ao novo ambiente, ou devem manter a barra tão alta, como para todos os outros?
As revisões de código de qualidade usam a mesma barra de qualidade e abordagem para todos, independentemente do seu cargo, nível ou quando entraram para a empresa. Seguindo o acima exposto, as revisões de código têm um tom amável, solicitam alterações sempre que necessário, e irão contactar os revisores quando estes tiverem muitos comentários.
As melhores revisões de código prestam mais atenção a fazer das primeiras revisões para os novos membros uma grande experiência. Os revisores têm empatia com o facto de que o marceneiro recente pode não ter conhecimento de todas as directrizes de codificação e pode não estar familiarizado com partes do código. Estas revisões colocam um esforço adicional na explicação de abordagens alternativas e apontam para guias. São também muito positivas no tom, celebrando as primeiras alterações à base de códigos que o autor está a sugerir.
Cross-Office, Cross-Time Zone Reviews
Code reviews get more difficult when reviewers are not in the same location. São especialmente difíceis quando os revisores estão sentados em fusos horários muito diferentes. Tive a minha quota-parte destas revisões ao longo dos anos, modificando códigos pertencentes a equipas nos EUA e na Ásia, ao mesmo tempo que estou baseado na Europa.
As boas revisões de códigos são responsáveis pela diferença de fuso horário quando podem. Os revisores pretendem rever o código nas horas de trabalho sobrepostas entre escritórios. Para revisões com muitos comentários, os revisores oferecer-se-ão para conversar directamente ou fazer uma videochamada para falar através de alterações.
Melhor revisão de código avisa quando as revisões de código se depararem repetidamente com problemas de fuso horário e procurarem uma solução sistémica, fora do quadro de revisão de código. Digamos que uma equipa da Europa está frequentemente a alterar um serviço que desencadeia revisões de código por parte do proprietário deste serviço sediado nos EUA. A questão ao nível do sistema é porque é que estas mudanças estão a acontecer tão frequentemente. As alterações são feitas na base de códigos correcta ou deve outro sistema ser alterado? A frequência das alterações será a mesma ou diminuirá ao longo do tempo? Assumindo que as alterações são feitas na base de códigos correcta e a frequência não diminuirá, será que a dependência entre escritórios pode ser quebrada de alguma forma? As soluções para este tipo de problemas não são muitas vezes simples e podem envolver refactoring, criação de novos serviços/interfaces ou melhorias de ferramentas. Mas resolver dependências como esta tornará a vida de ambas as equipas mais fácil e o seu progresso mais eficiente a longo prazo, o que significa que o retorno do investimento é muitas vezes bastante impressionante.
Apoio Organizacional
A forma como as empresas e as suas organizações de engenharia abordam as revisões de código é um grande elemento de quão eficientes podem ser. As organizações que as vêem como sem importância e triviais acabam por investir pouco para facilitar as revisões. Em culturas como esta, pode ser tentador simplesmente acabar com as revisões de códigos por completo. Engenheiros que defendem a realização de melhores revisões de código podem sentir-se isolados, sem apoio de cima e eventualmente desistir. O resultado é uma organização onde os problemas continuam a repetir-se e a agravar-se.
As organizações com boas revisões de código asseguram que todos os engenheiros participem no processo de revisão de código – mesmo aqueles que possam estar a trabalhar em projectos a solo. Encorajam o aumento da fasquia da qualidade, e as equipas facilitam discussões saudáveis sobre abordagens de revisão de códigos, tanto a nível da equipa como da organização. Estas empresas têm frequentemente guias de revisão de códigos para bases de códigos maiores, que os engenheiros iniciaram e escreveram. Organizações como esta reconhecem que as revisões de códigos ocupam um bom pedaço do tempo dos engenheiros. Muitas destas empresas acrescentam revisões de código como expectativas às competências do trabalho do programador, esperando que os engenheiros seniores passem uma parte maior do seu tempo a rever o código dos outros.
As organizações com melhores revisões de código têm regras rígidas em torno da inexistência de código que chegue à produção sem uma revisão de código – tal como as alterações da lógica empresarial não chegam à produção sem testes automatizados. Estas organizações aprenderam que o custo de cortar esquinas não vale a pena; em vez disso, têm processos para revisões expeditas para casos urgentes. Estas organizações investem na produtividade dos desenvolvedores, incluindo o trabalho contínuo para desenvolver revisões de código mais eficientes e melhorias de ferramentas. Executivos de engenharia úteis não precisam de convencer sobre os benefícios das revisões de códigos e outras melhores práticas de engenharia. Em vez disso, apoiam iniciativas sobre melhores ferramentas ou processos mais eficientes de revisão de códigos que provêm de equipas.
Quando as pessoas se deparam com revisões que se sentem hostis, sentem que podem falar e ter apoio total para resolver a questão. Engenheiros e gestores de topo consideram as revisões de código que não estão à altura do problema tanto como um código desleixado ou um comportamento deficiente. Tanto os engenheiros como os gestores de engenharia sentem-se habilitados a melhorar a forma como as revisões de código são feitas.
Start With Good, Make it Better
Good code reviews already have lots of good effort going into them. Eles fazem uma revisão minuciosa da mudança em si, evitam ser opinados com o tom dos comentários, e deixam claro os erros. Mantêm uma barra consistente, independentemente de quem esteja a solicitar a revisão e tentam tornar menos dolorosas as revisões de fuso horário cruzado, prestando mais atenção a estas. As organizações que têm boas revisões asseguram que cada desenvolvedor recebe e faz revisões de código regularmente. Esta já é uma barra alta – mas se chegar aqui, não pare. As revisões de código são uma das melhores formas de melhorar as suas competências, orientar outros, e aprender a ser um comunicador mais eficiente.
Aprimore as revisões de código melhorando continuamente os detalhes, mas também comece a olhar para as mudanças a um nível elevado também. Seja empático no tom dos comentários e pense em formas fora do processo de revisão de códigos para eliminar os erros frequentes. Fazer revisões de código especialmente acolhedoras para novos iniciantes e procurar soluções sistémicas para dolorosas revisões de fuso horário cruzado. As organizações que estão viradas para o futuro encorajam o investimento em ferramentas e melhorias de processos para melhorar as revisões de código, colhendo mais benefícios.
—br>Gergely é actualmente um líder em engenharia em Amesterdão. Este post do blog apareceu originalmente no blog do Gergely, The Pragmatic Engineer. Se quiser ler mais de Gergely, pode subscrever a sua newsletter mensal para os seus artigos sobre engenharia, liderança tecnológica e sistemas distribuídos. Se desejar contribuir com artigos para o blogue Stack Overflow, envie um email para [email protected].
Etiquetas: boletim, revisão de código, engenharia, desenvolvimento de software