Spike: Code review

# Spike: Code review Esse spike tem como objetivo adquirir informações sobre como o code review é aplicado nas empresas de tecnologia mundo afora para responder as seguintes perguntas: - Como as pessoas fazem code review? - Como pesar o custo e benefício do code review? - Como definir a granularidade do code review? ## Code review é importante O senso comum nos diz que implementar um processo de code review é muito importante, pois traz benefícios como: - Troca de conhecimento entre os membros do time - Diminui a quantidade de bugs - Melhora as estimativas de esforço - Descentraliza o conhecimento de determinadas partes do código - etc. O problema é que implementar um bom processo de code review é difícil e requer muito cuidado pois acaba lidando diretamente com a percepção de autoimagem das pessoas e isso geralmente é delicado e requer muita atenção para que o envolvimento interpessoal do time se mantenha saudável e sem comportamentos tóxicos. Além disso, um processo de code review mal implementado pode atrasar muito a entrega de novas funcionalidades, pois além de requerer bastante tempo da pessoa que está realizando a review, requer que o autor fique alternando entre contextos das funcionalidades que ele está atualmente desenvolvendo e funcionalidades que estão em review. ## Como fazer um code review? Existem vários aspectos do código que podem ser analisados em um code review. __A definição desses aspectos cabe à equipe__, mas em termos gerais, é comum focar em alguns dos aspectos a seguir: - Legibilidade e compreensibilidade Fazer um code review sem entender o código é impossível. Então, quase que de forma implícita, a primeira qualidade a ser analisada é sua legibilidade e compreensibilidade. Se o revisor não consegue entender em tempo hábil o que está sendo feito, um questionamento pode ser levantado. > Não consegui achar... > Não entendi o que essa função faz... - Performance A base de conhecimento de cada um é diferente, e em casos onde um revisor tem conhecimento de uma solução mais otimizada, um questionamento pode ser levantado. > O array.map tem algumas otimizações à mais que o for-loop, sendo desta forma mais recomendado para a maioria das situações... - Testes A equipe deve definir quais partes do código precisam de testes e que tipos de testes eles devem ser. > Foi definido na última reunião que novas funções de utilidade devem ter testes de... - Boas-práticas Apectos do código que se encontram no guia de estilos ou de boas-práticas. Aqui também cabe sugestões sobre a organização do projeto. > Ei, defina essa cor no /Themes/Colors e depois importe aqui, tá? > Acho que extrair essa pasta MyNewFeature para uma pasta central App/Features deixará o projeto mais organizado... > Ficou pendente esse TODO... ### Distingua opiniões de fatos Nunca exiga uma alteração em uma code review se você não tem argumentos bons para suportá-la, como por exemplo: documentações oficiais de bibliotecas, guias formais da empresa, padrões de código conhecidos, etc. Preferências pessoais não é um bom argumento. ### Comente apenas as alterações do autor Evite pedir que o autor da pull request corrija problemas que não foi introduzido por ele. Não é porque o código inserido toca em uma parte ruim da codebase que o autor é obrigado a refatorar tudo, pois isso muda o escopo da tarefa e dificulta as estimativas. Ao invés disso, recomenda-se criar uma story para que o problema seja resolvido depois (dívida técnica a ser paga). ### Cuidado com o tom Evite sempre fazer perguntas com um tom de julgamento, por exemplo: > Por que você não fez ____? Pois isso implica que uma solução simples e de senso comum não foi adotada pelo autor, e isso o força a se defender. Prefira sempre sugerir recomendações com citações a documentação e outras fontes e deixe de fora as palavras que podem ofender a pessoa: > Você poderia fazer ____, que traria como benefício ____. ### Evite piadas e sarcasmo Ao invés de comentar coisas como: > Você ao menos rodou os testes? Você poderia dizer: > Percebi que os testes estão falhando. Por favor corrija o código para que eles passem. ### Não faça review do código por mais de 60 minutos Nunca faça review de código por mais de 60 minutos pois a partir desse ponto a atenção aos detalhes tende a cair muito. É melhor fazer várias sessões menores de review e dar um tempo entre elas pro seu cérebro se recuperar. ### Não faça review de mais de 400 linhas de código por vez Se você tentar fazer review de muitas linhas de código de uma vez isso faz com que seja menos provável que você ache defeitos. Focar em menos de 400 linhas de código por vez deixa seu code review mais efetivo e mantém uma qualidade maior na codebase. ### Faça apenas um comentário por problema Em casos onde um linter específico para uma regra não esteja implementado, não saia comentando na pull request inteira o mesmo problema (por exemplo: "Por favor use o arquivo de cores"). Faça apenas um comentário pro problema explicitando que o mesmo deve ser corrigido em todos os lugares que foi violado. ### Converse com o autor Antes de começar a fazer uma review é recomendado conversar diretamente com o autor da pull request para que ele te explique de forma resumida o contexto da alteração e como a solução foi implementada. Isso ajuda a diminuir o tempo gasto nas code reviews. ## Sugestões de melhoria ### Definir os objetivos e expectativas Isso pode variar de empresa para empresa, mas é muito importante antes de começar a aplicar um processo de code review que todos estejam cientes dos objetivos e expectativas do processo. Seja para diminuir a quantidade de retornos do QA, diminuir o custo da manutenção do produto, etc. O ideal é que isso seja definido acomodando as necessidades da empresa e que preferêncialmente esses objetivos sejam mensuráveis para que seja possível acompanhar a efetividade do processo. ### Sistema de tags Utiliar um sistema de __tags para limitar o escopo__ do que pode ser apontado no code review. Essas tags representam qualidades do código que buscamos ao implementar um code review (legibilidade, performace, etc.). Caso um comentário __não se enquadre em um dos tags__ definidos pela equipe, é possível que o comentário foge do escopo definido. > #Style > Importar cores do arquivo /Themes/Colors... > #Performance > Usar array.map e não for-loop... > #Type > Você esqueceu de definir o tipo State.. ### Guia de boas práticas A criação de um __documento que podemos usar como referência__ e extender quando necessário, com definições de estilo ligadas a cada projeto. > Linguagem de desenvolvimento é inglês... > Definir propriedades de classe somente dentro do construtor... > Acessar propriedades de objeto.assim e não objeto['assim']... ### Checklist para o implementador Criar uma checklist simples para o implementador da story revisar o próprio código, de forma que os erros mais básicos não cheguem em review. Isso __evita que um PR volte por motivos muito simples__. Esse checklist poderia ser incorporado ao template do pull-request, inclusive. > [ ] Importei as cores do arquivo de cores > [ ] Defini/atualizei os tipos dos props e do state de todos os componentes que criei/modifiquei > [ ] Verifiquei que os nomes de todos os meus métodos/componentes/propriedades estão em inglês > ... ## Como responder a um code review? - Lembre que tudo que é apontado em um code review é um início de conversa, não uma condenação. Se você discorda, a soluçao é conversar com o revisor. - Caso a conversa não leve a um consenso entre implementador e revisor, busque uma terceira opinião e deixe a democracia resolver. - Responda a todos os comentários, mesmo que seja só pra dizer, 'Ajuste feito.' ## Mantendo uma cultura positiva Não importa quem introduziu o problema, o que importa é que ele foi pego antes de ir para o produto! Celebre isso. ## Referências [Code Review Best Practices - Palantir Blog - Medium](https://medium.com/palantir/code-review-best-practices-19e02780015f) [Code Review - The Ultimate Guide - freeCodeCamp](https://www.freecodecamp.org/news/code-review-the-ultimate-guide-aa45c358bbf5/)