1.0 - Escopo
Este documento visa demonstrar a importância da revisão de código e como faze-la em nosso ambiente de desenvolvimento.1.1 - Porque?
A revisão de código tem se mostrato útil em nosso time, desde a sua concepção. Já constatamos várias situações onde o código liberado iria gerar certa dor de cabeça assim que posto em produção. Desta forma, é importante que as regras e conceitos previstos sejam respeitados para evitar-mos problemas.O processo de revisão de código atua juntamente com a Política de Check-in (BC 65), afim de garantir a maior segurança possível (não a ideal) na liberação da versão. As regras propostas não estão aqui (e na política de check-in) para nos atrapalhar e tornar nosso trabalho moroso, e sim, para nos ajudar a não cometer erros, por isto é de suma importância que tudo o que é proposto seja seguido e respeitado.
1.2 - Ferramentas
O Review Assistant trabalha de forma integrada com o Visual Studio, principalmente no que diz respeito à controle de changesets. Maiores detalhes podem ser obtidos através do site oficial da ferramenta (https://www.devart.com/review-assistant/)1.3 - Instalação
O processo de instalação é relativamente simples, com apenas uma peculiaridade, vamos aos passos:Baixe o instalador através do site oficial (https://www.devart.com/review-assistant/) e abra o instalador. Há apenas uma peculiaridade durante a instalação, que é selecionar os componentes que devem ser instalados. Neste passo, selecione [Client Installation]:
Prossiga até o final da instalação e conclua o processo. Após a instalação, temos que configura-lo no Visual Studio.
No Visual Studio, acesse [Tools> Review Assistante> Options] e configure os parâmetros conforme abaixo:
O Review Server deve ser [http://cba-tfs1:85/ReviewAssistant];
O Login é feito via Windows Authentication (domínio), logo, não é necessário informar login e senha, bastando selecionar a opção Windows Authentication e clicar em Connect.
Se configurado conforme orientação, deverá conectar normalmente. Após realizar a conexão, é necessário configurar seu "local de trabalho"', nesta mesma página vá até a aba [Projects]:
Se tudo correu conforme o plenejado, sua estação já está apta a utilizar o Review Assistant.
1.4 - Solicitando um Review de um Changeset
Para solicitar um Review, é necessário utilizar o Review Board, para insto, acesse o menu [Tools> Review Assistant> Code Review Board]. Nesta parte do processo, clique no [+] conforme orientado abaixo:
Agora, adicione um Chengeset através do link [Add Revisions]:
Após selecionar o Changeset, devemos adicionar quem fará o review do changeset selecionado, para isto, adicione quantos reviewers forem necessários, veja:
Agora, clique em [Create] e a solicitação será criada e os envolvidos serão avisados.
1.5 - Fazendo um Review
Para fazer um Review é necessário utilizar o Review Board, para insto, acesse o menu [Tools> Review Assistant> Code Review Board]. Assim que é aberto, normalmente os reviews pendentes são exibidos, conforme imagem abaixo:
Neste ponto, dê dois cliques sobre o Review desejado (garanta que você é um dos reviewers escalados para a solicitação), agora, você verá esta tela:
Para analisar os arquivos e o que foi alterado em cada um deles, basta dar duplo clique em cada um dos arquivos, o Visual Studio será encarregado de abrir o comparador de código. Após analisar todos os arquivos, se tudo estiver bem, finalize a sua parte através do link [Complete Review> Accept Changes]. Caso você seja o único reviewer escalado, não esqueça de finalizar o review através do link [Complete Review> Close Review].
1.6 - Apontando um defeito no código durante a revisão
Ao se deparar com um defeito no código, que provavelmente gerará um BUG ao ser liberado para os clientes (erros menores também se encaixam neste ponto) é necessário apontar como um [Defect], onde o desenvolvedor terá que realizar a correção para então o review estar concluído. Para apontar um trecho de código com defeito, siga os seguintes passos:Selecione o trecho de código a ser apontado como defeituoso e clique com o botão direito, em seguida, clique em [Add Review Comment]:
Agora, descreva um pouco do problema para que o desenvolvedor possa se orientar e saber o que está incorreto ou inconsistente, veja:
Ao marcar como Defect, o desenvolvedor receberá um email informando da inconsistencia, onde poderá se orientar e prosseguir com a correção.
O comentário que fora adicionado somente poderá ser colocado como Close quando o defeito foi corrigido. Isto vale para o Review em questão também.
1.7 - Requisitando review de changeset que corrija um defeito apontado anteriormente
Se você fez um check-in que corrija um defeito apontado com algum review, os passos são um pouco diferentes para que se solicite o review deste changeset. Para ser mais claro, o changeset em questão deverá ser adicionado ao review que apontou o defeito (para manter uma espécie de "conversa", ou histórico para ser mais claro).Para adicionar um changeset ao review que apontou o defeito, acesse o Review que apontou o defeito e clique em [Add Revisions], veja:
Atenção! Um check-in que trata algo relatado em um review deve conter única e exclusivamente a alteração solicitada! Caso constatado que há mais alterações (não soliticadas), seu check-in poderá ser rejeitado.
1.8 - Avaliando um changeset que foi adicionado a um review
Quando um desenvolvedor corrige um defeito apontado por um review, o changeset desta correção é adicionado ao review que apontou o defeito. Assim, é necessário retornar a este review e revisar o novo changeset.Para isto, abra o review em questão, e agora, vamos aprender a navegar entre os changesets. Há na tela de review uma espécie de "barra", onde é possível selecionar quais changesets devem ser exbidos, veja:
Neste caso, o changeset 14950 foi o que recebeu um alerta de defeito e o 14958 foi o que corrigiu o defeito. Assim, podemos restringir a visão das modificações arrastando a "linha do tempo", onde selecionamos quais changesets serão visualizados na lista de arquivos logo abaixo.
Assim, após analisar o changeset que foi anexado, se tudo estiver correto, podemos fechar o comentário que apontou o defeito e prosseguir com o processo de review.
1.9 - Orientando via Review
Durante o review é muito importante ficar atento aos padrões de codificação, principalmente na qualidade do código. Neste ponto entra desde a nomenclatura, estrutura, organização, facilidade de leitura, escrita dentro dos padrões exigidos, etc. Deste modo, se for constatado um ponto que esteja em desacordo com tais critérios, é de suma importância orientar o desenvolvedor para que faça as adequações necessárias.Para que possamos fazer estas orientações de forma documentada, utilizaremos os comentários de reviews (da mesma forma como apontamos defeitos, porém, neste caso, sem marcar como um Defect]. Para tanto, ao se deparar com um trecho em desacordo, selecione-o e clique com o botão direito, em seguida, clique em [Add Review Comment], veja:
Agora, descreva a orientação:
O comentário será fechado somente após a orientação ser acatada e um check-in for feito para sanar a questão.
1.10 - Check-in em desacordo com a política de check-in
Todo check-in deve obedecer às regras previstas na política de check-in (BC 65 - Política de Check-in). Qualquer que seja o check-in, se estiver em desacordo com a política, deve ser rejeitado para que sejam realizados os ajustes. É de responsabilidade do reviewer tomar uma decisão consciente e exigir que a política seja respeitada (Exija excelência dos colegas, lembra?).1.11 - Leve em consideração
- Review é algo sério, dê DONE se, e somente se tiver a certeza de que está tudo certo (isto vale também para o fechamento de comentários dos reviews);
- Os comentários de cada review só podem ser fechados quando a situação foi sanada, nada pode estar em done com apenas uma promessa em mãos;
- Não deixe os reviews se acomularem, o tempo para revisar pode dobrar se estiverem acumulados, ainda mais se houverem retornos;
- Haja com espírito colaborativo, ajude nas correções, participe da solução dos problemas encontrados, caso seja necessário;
- Qualquer que seja a situação, se você ficou em dúvida ou viu algo estranho em algum ponto, jamais deixe a preguiça lhe dominar, faça algo à respeito, documente, converse, peça ajuda, mas nunca, nunquinha mesmo, cometa agressão passiva.