DEV Community: Marylly

Engenharia de Software: O tal Code Review

Marylly — Tue, 14 Sep 2021 23:16:17 +0000

O que é?

Code Review ou Revisão de código é uma prática onde o código desenvolvido para atender determinada demanda passa pela revisão de outras pessoas desenvolvedoras antes de ser integrada a uma versão principal de um software.

Idealmente não deve ser um processo mandatório, e sim um pacto do time, e o valor deve ser muito bem entendido para que existam benefícios.

Code Review x Práticas Agéis

Do ponto de vista do desenvolvimento ágil de software, o code review é um processo que impacta a velocidade do time e da entrega, e pode virar um gargalo se algumas boas práticas não são atendidas, logo uma má prática.

Contexto e Cenários + comuns

Considerando muitos times de desenvolvimento de software, muitos não detém do todo o conhecimento elementar que permitam um modelo de trabalho mais ágil utilizando trunk based sem um processo de code review estruturado e maduro. O trunk based deve ser o próximo passo após superadas essas deficiências e o processo de code review eliminado.

Como aplicar?

Apesar de alguns contrapontos, o processo de code review pode ser bem benéfico, e pode apoiar a maturidade e evolução técnica do time em muito aspectos.

Nessa prática, temos dois papéis:

Pessoa(s) quem desenvolveu o código
Pessoa(s) quem pode trazer pontos de melhoria, identificar contrapontos e sugerir formas distintas para resolver não somente o problema de implementação, como problemas relacionados a demanda do código.

Pode ser feito de duas maneiras: (1) Pessoalmente com as pessoas que a autora do código confia e se sente segura, ou sua liderança imediata. (2) Utilizando o recurso de Pull Request oferecida por ferramentas de host de versionamento (GitHub, GitLab, BitBucket, etc)

A expectativa do processo é responder algumas das perguntas relacionadas abaixo:

1. Código limpo ou Clean Code: É possível as pessoas lerem o código e entender o seu propósito (comportamento/resultado)?

2. Diretrizes do Projeto: Perfomático, escalável, enxuto, padrões de projetos, padrões de arquitetura, style guide, etc.

3. Funcionalidade: O comportamento do código atende as expectativas da pessoa desenvolvedora e as pessoas que irão usar: clientes, etc? Efeitos colaterais no comportamento e/ou funcionalidades já existentes no software?

4. Complexidade: As mesmas tarefas e resultados do código podem ser executadas com um código mais simples e enxuto?

5. Testes: O código está sendo testado? Existem cenários que cubram os cenários feliz e infeliz do processo principal desenvolvido no código? Se um comportamento indesejado ou inesperado surgir, os testes sinalizaram?

6. Nomes: Os nomes utilizados no código trazem uma conexão com os processos e problemas de negócio que o código está sendo desenvolvido para resolver? Os nomes empregados nas variáveis, classes, métodos, funções apoiam o entendimento do comportamento ou da saída de código em revisão?

7. Comentários: Os que foram utilizados estão fácil de compreender, curtos e realmente úteis onde aplicados?

8. Efeitos colaterais: Impacta na comunicação e/ou comportamento de aplicações internas/externas e de parceiros? Quebra de contratos de comunicação?

9. Documentação: A documentação de apoio precisa ser atualizada? Contém o que precisa para executar alguma atividade ou tarefa relacionada ao código?

Benefícios

Apoia o engajamento do time com a saúde do código;
Apoia no aprendizado de linguagens, frameworks, paradigmas, etc;
Acelera o engajamento de novas pessoas desenvolvedoras sobre o que é esperado do código;
A medida que as boas práticas e melhorias são aplicadas, novas formas são discutidas e absorvidas, aumentando a qualidad;
Fortalece a confiança da pessoa desenvolvedora e do time em deploys de alta qualidade;
Promove discussões sobre: (1) Tecnologias usadas e novas (2) Discussões sobre arquitetura de código (3) Discussões sobre boas práticas;
Promove o compartilhamento de conhecimento e a cooperação;
Apoia na identificação de refatorações e débitos técnicos que podem ser trabalhados posteriormente.

Contrapontos

Pode gerar estresse e ansiedade para as pessoas autoras do código, principalmente para pessoas novas no time/projeto.
Pode se tornar um gargalo no ciclo de desenvolvimento de software.

RECOMENDAÇÕES

Autora do Código

Na apresentação ou descrição da revisão, comunique o objetivo da implementação, e se for necessário, as idéias por traz da solução desenvolvida;
Se o processo for por PRs, faça-os de forma incremental com pouco conteúdo e sinalize o trabalho ainda em andamento (vulgo WIP ou Work in Progress), para não desestimular as pessoas revisoras pelo volume ou pela falta de tempo para revisar adequadamente;
Evite enviar para revisão pedaços de código não-funcionais ou que não agregam ao processo. Atrapalha a revisão e aumenta o tempo utilizado para entender o que o código faz;
Evite códigos de coisas que ainda vão ser desenvolvidas no futuro (as vezes coisas não confirmadas). Ex. Classes vazias, métodos/funçõe vazios, as vezes só a sua assinatura, TO-DOS, etc;
Não espere pelo tempo das pessoas revisoras, sinalize as envolvidas, afinal todas temos prazos para serem atendidos, e a entrega é do time, pelo alguém do time deve se organizar para fazer a revisão;
Se for fazer revisão pessoalmente, agende com a pessoa e reserve um tempo para focar adequadamente no processo;
Se não houver consenso ou ocorrer conflitos, busque a liderança ou outras pessoas para chegar na melhor solução possível para o contexto e momento;
Em revisões privadas, compartilhe os resultados num comentário do PR ou num canal comum com o time para que todas entendam e aprendam com a informação;
Evite código/artefatos desnecessários: Código comentado que não está e/ou nem será utilizado, arquivos que não precisam ser versionados ou que são temporários.

Revisora do código

Evite criticar a pessoa ou código;
Seja propositiva nos comentários, e compartilhe suas razões;
Foque nas diretrizes do projeto;
Evite compartilhar opiniões pessoais, faça de forma privada, somente você e a pessoa autora;
Não compartilhe feedbacks negativos ou construtivos, faça de forma privada, somente você e a pessoa autora;
Se existir dúvida se vai ofender ou gerar conflitos, faça de forma privada ou busque apoio para transmitir a mensagem adequadamente;
Nem sempre as preferências da pessoa revisora é uma regra que deve ser adotada pela pessoa autora do código, e isso deve ficar bem entendido pelas pessoas envolvidas;
Sinalize quando um comentário é apenas uma sugestão, não necessariamente algo mandatório, e a pessoa autora pode tomar a decisão de fazer ou não;
Busque o consenso em detrimento da imposição;
Abordagens interessantes de solução foram apresentadas, reconheça, aprecie a pessoa autora do código, reforce as coisas boas e que trazem valor;
Se não conhece muito bem a codebase, comece pelos testes para entender o comportamento desenvolvido e os elementos do código utilizado para confrontar com a proposta inicial da demanda.

Princípios Recomendados

1. Novas demandas emergentes: Podem surgir necessidades de reavaliação da implementação, refatoração e até necessidade de criar novas funcionalidades. As pessoas da liderança e de negócio devem ser sinalizadas e a solução replanejada ou refatorada de acordo com o prazo, pessoas e recursos disponíveis, evitar absorver esse trabalho emergente num trabalho iniciado e identificado através de uma revisão de código;
2. Ambiente seguro e inclusivo: NÃO é um espaço para repressão das pessoas autoras por preconceitos por parte das pessoas revisoras, pelas características da pessoa autora do código (raça, gênero, origem, religião, inclinação política, comportamento e/ou aparência), todas as pessoas DEVEM ser respeitadas pelo o que REALMENTE são;
3. Espaço de aprendizado: NÃO é um espaço para as pessoas autoras serem reprimidas por falta de alguns conhecimentos, e sim, para suprir deficiências técnicas, aprender novas formas de trabalho, exporem suas idéias, fortalecerem seus conhecimentos e obter feedback sobre a evolução do trabalho antes de ir para ambiente produtivo;
4. Revisões rápidas: O time deve ser encorajado a fazer as revisões assim que possível, o período máximo de um dia de trabalho para ser concluído.

Conclusões

Apesar do Code Review não ser considerada uma boa prática, pode ser um espaço de muito crescimento e amadurecimento das pessoas envolvidas, e deve ser utilizado como um trampolim para a evolução para o formato trunk based.

Se conhece outras formas para a prática do processo, compartilhe comigo nos comentários, seria muito legal continuar a conversa e evoluir sobre o tema. =]

ATENÇÃO: Esse conteúdo é a consolidação das impressões e opiniões da autora sobre o assunto, resultado de vivências e processos empíricos que trouxeram resultados para contextos específicos, não há garantia que é aderente a qualquer contexto e/ou time de desenvolvimento de software.

Referências

Google Inc: The Standard of Code Review, Engineering Practices. Acessado em 10 de Setembro de 2021: https://google.github.io/eng-practices/review/reviewer/standard.html

Yu, Chak Shun; Better Programming Blog: 5 Actionable tips to deliver higher quality code reviews today.
Acessado em 14 de Setembro de 2021: https://betterprogramming.pub/5-actionable-tips-to-deliver-higher-quality-code-reviews-today-de422cd538df

Clean Code: Exceptions e Tratamentos de Erros

Marylly — Thu, 02 Apr 2020 23:31:06 +0000

Esse artigo é um de uma série que fala sobre vários tópicos relacionados a Código limpo, seguem os tópicos relacionados abaixo:

Código Limpo: 1. Introdução
Código Limpo: 2. Funções
Código Limpo: 3. Exceptions e Tratamento de Erros [Você está aqui!]

No nosso dia-a-dia, nós temos que lidar com erros, problemas e direções que algumas situações tomam na nossa vida, algumas podemos reverter, diminuir os impactos ou simplesmente aceitar o fato em sí, decisões e fluxos de fatos podem caminhar para erros e problemas. Contextualizando, imagine que você tenha um celular e você contrata um seguro, para reduzir os impactos negativos financeiros, perda de bem ou só o fato de ficar sem o aparelho celular, você não deseja que esses problemas aconteçam, mas caso sim, o seguro existe para minimizar esses impactos negativos.

Assim como na vida real na situação contada acima, estamos passíveis de erros e problemas nos softwares que construímos e utilizamos, e é uma ferramenta que pode reverter ou minimizar os impactos negativos desses erros são as Exceptions ou Exceções.

O conceito de Exceptions nasceu na linguagem LISP e é uma ferramenta que permite identificar de forma amigável e tratar erros que estão fora do fluxo normal e esperado do software.

Como pessoas desenvolvedoras, é nosso dever reduzir os impactos negativos dos erros de software na vida das pessoas que utilizam o mesmo, e assim como na vida, podemos escolher lidar com (ou ignorar) o ocorrido.

Muitas linguagens possuem suporte a Exceptions, mas existem algumas linguagens que não possuem, C, Perl, Pascal, Golang são exemplos que não possuem suporte.

Principais fontes de Exceptions

Falhas de hardware;
Falhas de dispositivos;
Falhas de rede e comunicação;
Erros de programação;
Erros de sintaxe;
Entrada dados com tipo incorreto.

Tratando erros

Algumas das estruturas (statement) disponibilizadas por linguagens de programação é a try-catch-finally ou a utilização de error handler ou wrappers. Essas estruturas permitem que para determinado fluxo de execução, seja possível recuperar-se sabendo qual erro, a identificação
e alguma informação específica do fluxo para resolver ou contornar o problema.

Exceções verificadas

O conceito de exceções verificadas foi criada e disponibilizada na linguagem Java por Jim Waldo, e consiste em incluir na assinatura de todo método a lista de todas as suas exceções que pode passar para a sua chamada. Saber quais possíveis Exceptions pode ser muito benéfico para leitura e entendimento do que acontece num método, mas toda vez que uma nova Exception é adicionada num método ou função, é necessário:

modificar a assinatura do método/função;
modificar as chamadas adicionando um Throw para nova Exception.

E podem:

gerar uma alteração em cascata de várias chamadas do método/função;
acrescentar complexidade do código;
quebrar o encapsulamento da implementação, porque no tratamento do throw é preciso dar detalhes da implementação da Exception para fazer a tratativa do erro;
violar o Princípio Aberto-Fechado (Open-Closed Principle) do SOLID de classes estarem abertas para extensão, mas fechadas para alteração.

Exceções não verificadas

Esse tipo de exceção não precisa ser explicitada para o seu chamador (método ou função). Possuem as vantagens em relação as Exceções verificadas:

não quebra o encapsulamento, menor dependência da implementação das Exceptions;
não viola o Princípio Aberto-Fechado (Open-Closed Principle) do SOLID;
menos código, menos bug;
código limpo sem todas as tratativas de todas as Exceptions possíveis.

Porém existe a desvantagem que deixa a implementação do código misteriosa, não tendo muitos detalhes das Exceptions possíveis, talvez exista no código apenas as Exceptions mais críticas tratadas.

Boas práticas

se a Exception pode ser descartada por uma correção no código, FAÇA A CORREÇÃO;
tenha uma classe abstrata que padronize a estrutura e os atributos de todas as informações necessárias quando uma Exception for levantada;
crie tratativas para Exceptions especifícas, prefira as classes de Exceptions concretas;
forneça contexto mínimo na sua Exception para identificar a origem e a localização do erro (onde isso aconteceu mesmo no código?);
contextualize suas Exceptions, por exemplo, tenha a classe concreta LoginException herdando a classe abstrata Exception padrão e onde centraliza todos os erros tratados do contexto da funcionalidade de login;
no retorno de uma função ou método que seja Null, substitua por uma Exception, evitando verificações desnecessárias se um retorno é = a Null sem muita informações do por que tem este retorno;
forneça a Stack Trace somente se necessário, caso contrário disponibilize o mínimo possível de informação (Isso pode virar uma falha de segurança);
tenha em mente que essas informações podem ser exibidas num erro na tela do seu cliente que pode ficar confuso ou até diminuir a confiança do mesmo;
tenha em mente que essas informações podem ser exibidas para alguém mal-intencionado que pode usar para identificar falhas que podem ser exploradas no seu código;
tenha em mente que isso pode ser uma informação muito útil coletada no monitoramento do seu ambiente: utilizada, consolidada e mensurada para feedback rápido de problemas no seu software durante a utilização do mesmo;
por favor 🙏, testem suas Exceptions.

Conclusão e reflexão

Tenha em mente que a utilização de Exceptions não previne erros. A ferramenta ajudará a errar melhor ou menos para que os problemas sejam mais rapidamente identificados e corrigidos, além de trazer uma qualidade na construção do seu código.

Boas Exceptions e até mais! =]

Referências

[1] Martin, Robert. Código Limpo: Habilidades Práticas de Agile Software. Altabooks, 2011. Rio de Janeiro.
[2] Wikipedia. Tratamento de Exceções. Disponível em https://pt.wikipedia.org/wiki/Tratamento_de_exce%C3%A7%C3%A3o, acessado em 02 de Abril de 2020 às 17:48.
[3] Wikipedia. Exception Handling. Disponível em https://en.wikipedia.org/wiki/Exception_handling, acessado em 02 de Abril de 2020, às 19:32.
[4] Coding Horror. The First Rule of Programming: It's your fault. Disponível em https://blog.codinghorror.com/the-first-rule-of-programming-its-always-your-fault/, acessado em 02 de Abril de 2020 às 20:10.
[5] Coding Horror. Retrowing Exceptions. Disponível em https://blog.codinghorror.com/rethrowing-exceptions/, acessado em 02 de Abril de 2020 às 20:19.
[6] Coding Horror. What's Worse Than a Bad Error? Disponível em https://blog.codinghorror.com/whats-worse-than-a-bad-error-message/, acessado em 02 de Abril de 2020 às 20:24.
[7] Coding Horror. Creating Even More Exceptional Exceptions. Disponível em https://blog.codinghorror.com/creating-even-more-exceptional-exceptions/, acessado em 02 de Abril de 2020 às 20:29.

Clean Code: Comece por aqui

Marylly — Tue, 24 Mar 2020 22:26:59 +0000

Esse artigo é um de uma série que fala sobre vários tópicos relacionados a Código limpo, seguem os tópicos relacionados abaixo:

Código Limpo: 1. Introdução [Você está aqui!]
Código Limpo: 2. Funções
Código Limpo: 3. Exceptions e Tratamento de Erros

Existem muitos critérios e aspectos que podem caracterizar um "bom código" que devem ser considerados na construção do mesmo, temos muitos conteúdos que nos orientam como fazer.
Considerando um aspecto bem interessante seria o quanto isso pode ser constituído de critérios subjetivos e pessoais. Muitos desses critérios podem estar relacionados com a experiência e vivências de uma pessoa desenvolvedora, inclusive o Clean Code nasceu de boas e más experiências de seus idealizadores, e mesmo na literatura é possível que essas práticas mudem de acordo com a evolução do desenvolvimento de software, assim como podem ser aprimoradas. Sobre o que temos de comprovado sobre os benefícios do uso de Clean Codes são as seguintes características:

Manutenibilidade (Maintainability): Código fácil de modificar e atualizar;
Debugging – Código menos sujeito a erros e mais fácil de isolar e corrigir erros;
Escalável (Scalability): Código modular, reutilizável e fácil de acomodar mudanças futuras;
Colaboração (Collaboration): Código permite que muitas pessoas entendam o código de outras pessoas e consiga fazer o trabalho necessário;
Documentação (Documentation): Código auto-explicativo que reduza a necessidade excessiva de comentários;
Eficiência (Efficiency): Código previne duplicidade e complexidade desnecessária, melhorando performance;
Legibilidade (Readability): Código fácil de ler, reduz confusão e melhora a Manutenibilidade.

Outros aspectos relacionados:

experiência maior com estruturas procedurais (paradigmas imperativos);
experiência com orientação à objeto;
experiência com níveis baixos ou altos de granularidade de métodos e/ou funções;
influência de colegas de trabalho que dizem se um código está bom e limpo;
boas e más experiências com projetos anteriores e cultura de time que tem esse domínio muito bem definido;
conhecer o domínio e regras de negócio e o mercado atendido.

Todos os pontos acima colaboram com a leitura e compreensão do código dando sentido ao que está sendo interpretado (alguns casos nem tanto, rs).

Não existe uma regra de quais conceitos devem ser aplicados ou não no dia-a-dia, e não existe uma receita que garanta os resultados. Podem variar de contexto para contexto, podem ser agregados gradativamente e adotados a medida que os benefícios são observados e trazem valor ao desenvolvimento.

Sinta-se a vontade para ter suas próprias opiniões e critérios e criar os seus critérios de Código Limpo! =]

Faltou alguma coisa?
Se tu acha algo no artigo ficou confuso, coloca nos comentários ou me manda uma mensagem. Se conhecer mais dicas e práticas, coloca nos comentários para a galera já ler na sequência, vamos enriquecer nossa discussão sobre o assunto. =]

Próximo artigo >> Funções

Referências:

Shafrir, Nir; DZone: Best Practices for Writing Clean Java Code. Disponível em: https://dzone.com/articles/best-practices-for-writing-clean-java-code. Acessado em 25 de Setembro de 2023 12:57

Clean Code: Funções

Marylly — Tue, 24 Mar 2020 20:56:43 +0000

Esse artigo é um de uma série que fala sobre vários tópicos relacionados a Código limpo, seguem os tópicos relacionados abaixo:

Código Limpo: 1. Introdução
Código Limpo: 2. Funções [Você está aqui!]
Código Limpo: 3. Exceptions e Tratamento de Erros

Vamos falar um pouco como podemos melhorar a compreensão de nosso código no contexto de funções.

IMPORTANTE: Todas as sugestões e práticas aqui descritas se aplicam a funções, métodos e/ou variações, independente do paradigma escolhido ou da linguagem que está sendo utilizada e aplicando os conceitos, então quando me refiro somente por função ou método, estou falando da conceitos em ambos.

Bom, acho que antes de falarmos de como construir um código limpo e boas práticas, vamos falar do que precisamos evitar fazer.

Como NÃO ter um código limpo com funções/métodos

Código NÃO limpo nós normalmente identificamos logo na primeira leitura de um trecho de código e sentimos que não estamos entendendo o que está fazendo, o que está acontecendo. Ter certa complexidade no código e/ou os nomes não dizem muito sobre o que está acontecendo no código.
Seguem abaixo alguns aspectos que podemos considerar quando estamos construindo ou refatorando um código existente:

1.Evite nomes parecidos, podem confundir quando colocar a chamada em outro lugar:

func upTime() {
    // current UpTime
}

func updTime() {
    // Update time
}

Já teria gerado um bug com certeza, porque ÓBVIO que eu chamaria a função incorreta.

2.Evite acrônimos que confundam, podem ser mal interpretados e confundir a pessoa desenvolvedora:

func genymdhms() {
    // Generation Timestamp (Y-m-d h:m:s)
}
func modymdhms() {
    // Modification Timestamp (Y-m-d h:m:s)
}

Não iria deduzir nunca o que essas funções fazem, sofrido ("Crying in Spanish").

3.Evite as letras "L" e "Ó" minúsculas que podem parecer "1" e "0"(zero) respectivamente, podem deixar o código confuso, como o exemplo abaixo que já enche os nossos olhos de lágrimas de sofrimento:

    int a = 1
    if (O == 1)
        a = O1
    else
        l = 01

4.Evite nomes que tenham no nome apenas uma letra, lendo e interpretando o código abaixo na base do ódio:

    x = 1
    a = x + 2

5.Evite usar números sequenciais em nomes ( a1, a2, ..., aN ), não expressa nenhuma informação que ajude a compreender o contexto do código.

6.Evite palavras distintas que podem expressar informações do mesmo contexto ou não. Leio o código abaixo e me sinto como o confuso John Travolta em Pulp Fiction:

func getProductData() {
    // Gets product id, name and description
}
func getProductInfo() {
    // Gets product specification
}

7.Evite adicionar contextos desnecessários como o nome ou as siglas da empresa em todas as classes, métodos e funções, prejudicando a pesquisa:

func myCompanyNameGenTimestamp() {
    ...
}

func myCompanyNameUpdTimestamp() {
    ...
}

8.Evite linguagem informal e/ou gírias. Exemplos: whack(), eatMyShorts(), abort().

9.Quanto mais longo é um programa, mais tempo e difícil para entender o que ele faz.

Como construir um código limpo com funções/métodos

1.Crie nomes significativos 1: Acho que todo mundo se depara não com o desafio de criar uma função método com um cálculo matemático, mas sim, como nomear essa função que executa este cálculo matemático complexo.

"Escolher bons nomes leva tempo, mas economiza mais." - Robert C. Martin

Funções/Métodos devem fazer apenas uma coisa, devem fazê-la muito bem e apenas ela, devem comunicar o que fazem e como usa de forma compreensível 2 e que revelem seu propósito. Cuide de seus nomes e troque quando encontrar melhores. Exemplo de função com nomes bem definidos: Números ímpares num função:

func oddNumber(number: int) bool {
    if(number / 2 % 0) {
        return true
    }
}

2.Use nomes a partir do domínio(projeto, negócio, objetivo) da solução ou do problema da aplicação

3.Nomes curtos geralmente são melhores contanto que sejam objetivos e compreensíveis.

4.Crie nomes que sejam pronunciáveis e pesquisáveis e de fácil escuta:

func generationTimestamp() {
    // Generation Timestamp (Y-m-d h:m:s)
}

func modificationTimestamp() {
    // Modification Timestamp (Y-m-d h:m:s)
}

Refatorei o código das funções com acrônimos e já vejo uma luz no fim do túnel de que posso melhorar, como a vida é bela!

5.Blocos dentro de instruções if/else, while devem ter uma linha, porque a chamada dentro do bloco pode receber um nome mais descritivo.

Existe o receio de renomear as coisas por outras pessoas do time serem contra, todos devem na verdade agradecer que os nomes mudaram para melhor.

Perguntas boas para se fazer durante o processo:

Como fazer uma função/métodos transmitir seu propósito?
Quais atributos das nossas funções/métodos que permitirão um leitor comum deduzir o tipo de programa ali contido?
Funções devem ser pequenas: Qual o tamanho ideal? 3, 4 linhas?

Faltou alguma coisa?

Se tu acha algo no artigo ficou confuso, coloca nos comentários ou me manda uma mensagem. Se conhecer mais dicas e práticas, coloca nos comentários para a galera já ler na sequência, vamos enriquecer nossa discussão sobre o assunto. =]

Referências usadas no artigo:

[1] Martin, Robert, Código Limpo: Habilidades práticas do Agile Software, 2011, Alta Books, Rio de Janeiro.

[2] Fowler, Martin, Refactoring: Improving the Design of Existing Code, 2019, Pearson, EUA.