DEV Community: Rodrigo GS Silva

O código não te pertence: A importância do código limpo.

Rodrigo GS Silva — Mon, 16 Mar 2020 16:03:06 +0000

Durante o início da minha carreira não me importei em como ficava meu código final. O “bom e velho”~~contém ironia~~ go horse era meu modus operandi. Simplesmente codificava sem parar e sem pensar demais. Muito control+c/control+v, gerando vários pontos de duplicidade. Achava que para programar bastava entender a sintaxe da linguagem, ter lógica de programação e entregar o que era solicitado funcionando.
Isso fazia com que eu escrevesse, mesmo que indiretamente, um código somente para que eu mesmo pudesse lê-lo.

Entre a experiência que adquiri com o tempo e os estudos, conheci um conceito que entendo como fundamental para se tornar um desenvolvedor melhor e o qual defendo e compartilho com meus pares. O código limpo.

E porque essa importância tão grande? Simples, quando escrevemos código na empresa onde trabalhamos ou no projeto open-source que contribuímos, compartilharemos este código com outras pessoas. O código desenvolvido por nós não nos pertence. E, por se tratar de algo que será utilizado e evoluído por outras pessoas, é de suma importância que seja legível. Nosso trabalho é, em algum nível, comunitário e, portanto, não é feito de nós para nós mesmos apenas. Temos que nos preocupar, enquanto membros de uma equipe, com todo o organismo responsável por aquela aplicação.

E é exatamente isso que o código limpo prega, que devemos escrever nossos softwares de forma coesa. Não somente para nós mesmos, mas para que as demais pessoas desenvolvedoras que peguem o código feito por nós consigam ler e entender rapidamente, podendo evoluí-lo (ou corrigi-lo quando necessário) de forma eficiente sem precisar de ~~gambiarras~~ workarounds ou grande esforço mental para entendê-lo. É importantíssimo compreendermos que não trabalhamos sozinhos e que desenvolver código testável, manutenível e legível é benéfico para todas as pessoas envolvidas. Estamos todos trabalhando para alcançar um mesmo objetivo e se todos assimilarem que código bem escrito é essencial para a vida útil e evolução do software, estaremos um passo mais próximo do sucesso.

Robert C. Martin (mais conhecido como Uncle Bob) escreveu um livro de título homônimo ao conceito, onde explica, com exemplos, formas de se escrever código limpo. Nele, Uncle Bob inicia brincando que a métrica para qualidade do código é quantidade de “WTF por minutos” que falamos ao lê-lo. Quanto mais vezes, pior.

Vou trazer à tona dois pontos que acho importante para que possamos plantar a sementinha do código limpo em nossas mentes e começar a entender o conceito e sua necessidade.

NOMES

Devemos dar nome significativos às coisas. Nomes legíveis dão contexto às coisas. Não devemos escrever código que seja lido apenas para os interpretadores e máquinas. Em um primeiro momento, pode parecer legal e diferentão, no entanto, fazer a leitura deste código dias ou meses depois pode se tornar um tormento.
Martin Fowler, outro grande arquiteto de software, foi categórico ao dizer “qualquer idiota pode escrever código que o computador entende. Bons programadores escrevem código que outros humanos entendem”.
Vejamos o exemplo abaixo:

O que significam as variáveis cmt e p? Qual é o contexto desta aplicação? Somente com este pequeno trecho de código é impossível dar qualquer informação acerca da aplicação na qual está inserida.

Perceba que no segundo exemplo a leitura é fluída. Você compreende em qual contexto esse trecho está inserido sem nem conhecer o resto do código fonte do sistema. Ler uma função de cima para baixo como se fosse texto corrido é um bom indicativo que a função está bem escrita, enquanto no exemplo de cima, é necessário mais conhecimento sobre outros trechos da aplicação para alcançar o mesmo nível de entendimento. O esforço mental para entendê-lo é maior e devemos evitar a todo custo esse mapeamento mental.

Selecione uma palavra por conceito. Imagine que uma aplicação qualquer tem vários pontos onde objetos são inseridos no banco de dados, devemos utilizar sempre a mesma palavra para descrever a ação. Funções como “adicionarUsuario”, “incluirMensagem”, “salvarRegistro” podem causar confusão em outra pessoa que estiver trabalhando no sistema pois a falta de padrão pode dar a entender que essas funções executam coisas diferentes. Selecione uma - neste caso, entre adicionar, incluir ou salvar - e mantenha sempre ela por todas as funções.

Utilize nomes passíveis de busca, por exemplo, uma constante “SEGUNDOS_POR_DIA” é mais fácil de ler e entender seu objetivo do que “SGS_DIA” ou “SPD”. Não devemos ter medo de dar nomes grandes para as coisas. É preferível que façamos isso, desde que a intenção e o objetivo daquela coisa fique explícita, do que economizar teclas e deixar um nome obscuro.

Além disso, use nomes pronunciáveis. No exemplo anterior, cmt, p e cmtArr não são palavras conhecidas da nossa língua, por isso, fica difícil pronunciar seus nomes. Na refatoração, as variáveis foram nomeadas com palavras que conseguimos pronunciar, são palavras que existem e que conhecemos, isso facilita na leitura e até na hora de conversar com alguma outra pessoa sobre aquele trecho específico.

Seguindo a regra acima vamos evitar também a utilização de notação húngara. Antigamente fazia sentido sua utilização, pois, tanto as linguagens de programação quanto os editores não eram tão avançados a ponto de informar à pessoa quando havia um erro de tipagem. Atualmente, os editores já são capazes de identificar e apontar esse tipo de erro durante o tempo de desenvolvimento. Portanto, colocar algo como public string strNome; não faz sentido, pois o tipo já é atribuído na declaração da propriedade e qualquer valor diferente de string que for passado à propriedade será alertado pelo editor.

FUNÇÕES

Uncle Bob escreve:

“As funções devem fazer apenas uma coisa. Devem fazê-la bem. Devem fazer apenas ela”.

Esta descrição está diretamente ligada ao Single Responsibility Principle, primeiro conceito do SOLID. O qual não irei me estender aqui. Mas #ficaAdica de estudo.

Um indicativo de que a função é responsável por executar mais de uma coisa é tentar nomeá-la deixando explícito tudo o que ela faz. Se este nome tiver algo como ValidarEAdicionar, obviamente a função está executando duas funcionalidades distintas e, portanto, é uma função passível de refatoração. Como a regra é que a função seja responsável por apenas uma coisa, dar nome para ela se torna algo mais fácil caso a regra seja seguida.

Outra forma de saber se uma função é responsável por mais de uma coisa, é o tamanho dela. Muitas linhas de código, geralmente, indicam que existe mais de uma coisa acontecendo ali. Como expliquei anteriormente, para que o código seja legível, ele deve ser escrito de forma que possamos lê-lo de forma corrida “como um texto” e com uma função com poucas linhas de código é mais fácil alcançar este método de leitura.

Um ponto importante é que, como uma função deve executar apenas uma tarefa, consultas e comandos devem ser funções distintas. Ou seja, sua função de obter dados deve ser uma e a função que atribui o valor outra. No livro, Uncle Bob exemplifica com:

E sua utilização da seguinte forma:

A função set deve ser responsável unicamente por atribuir o valor ao atributo. Até porque o retorno dela não deixa claro em quais momentos será retornado true ou false.
Neste caso, ele refatora o código para ficar da seguinte maneira:

Desta forma fica claro qual o objetivo de cada função.

Vale lembrar que um código limpo é, também, um código testável. Para tanto, é preferível que as funções tenham nenhum, um ou dois parâmetros apenas. Claro que devemos avaliar a necessidade de cada parâmetro e pode haver casos onde é preciso utilizar três ou, em alguns pouquíssimos casos, mais. Porém, é aconselhável que não utilizemos mais do que dois parâmetros, pois, a quantidade de combinações possíveis de valores para ambos os parâmetros ainda é aceitável quando trabalhamos com dois ou menos. A partir de três, as combinações começam a expandir em nível exponencial, o que torna a cobertura de teste mais complexa e, portanto, mais difícil de atingir um nível satisfatório.

Quando uma função recebe três ou mais parâmetros, é preferível que, em vez disso, se crie uma classe e uma instância dela seja o único parâmetro para aquela função.

Por fim, uma função não deve conter efeitos colaterais. O efeito colateral é quando sua função promete fazer uma coisa, mas, por trás dos panos, faz outra também. E esta segunda coisa não era prevista por quem faz a chamada à função. No livro, Uncle Bob exemplifica esta parte da seguinte forma:

Podemos ver que, além de validar a senha, este método também é responsável por inicializar a sessão. Isto é gravíssimo, pois, outra pessoa que chamar o método sem conhecer o código fonte irá esperar que ele apenas faça a validação da senha. Essa sessão inicializada não é esperada e, provavelmente, em algum momento isso será motivo de dor da cabeça.

OUTRA DICA

Além do código limpo, outro conceito que me ajudou a melhorar a legibilidade do meu código é o Object Calisthenics. Não irei falar sobre aqui, pois o link acima já é bem detalhado sobre cada uma das regras que o regem.

CONCLUSÃO

Veja, neste artigo apenas introduzi dois pontos iniciais sobre o código limpo. O livro de Robert Martin é muito mais denso e detalhado do que isso.

A intenção aqui é provocar você a compreender que, enquanto membro de uma equipe, deve se preocupar com que o código desenvolvido seja legível para todas as pessoas envolvidas e que, se todos pensarem dessa mesma forma, a vida útil do software será maior, seu tempo de resolução de problemas será menor e a sanidade mental das pessoas será mantida.

Arquitetura de Software: simples e clara é subestimada

Rodrigo GS Silva — Thu, 20 Feb 2020 19:19:13 +0000

O texto abaixo é uma tradução livre do artigo escrito por Gergely Orosz, Software Architecture: Clear and Simple Design is Underrated. Sintam-se convidados a sugerir correções e melhorias na tradução.

Eu já pude, muitas vezes, projetar e desenvolver sistemas de grande escala. Fiz parte da reescrita dos sistemas distribuídos de pagamento do Uber, projetei e entreguei o Skype no Xbox One e o framework mobile open-source do Uber, RIBs. Todos esses sistemas tiveram projetos minuciosos, passando por várias iterações, com muito whiteboarding e muito debate. Os projetos se tornaram documentos de design que eram circulados para mais feedbacks antes de iniciarmos a desenvolver.

Todos esses sistemas eram de larga escala: centenas de desenvolvedores os construíram – ou estavam envolvidos neles – e alimentavam os sistemas utilizados por milhões de pessoas por dia. Eles também não eram apenas projetos novos. O sistema de pagamento reescrito tinha que substituir dois sistemas já existentes, que eram utilizados por dezenas de outros sistemas e times. Tudo isso, sem impactar no negócio. Essa reescrita foi um projeto que algumas centenas de engenheiros trabalharam simultaneamente portando funcionalidades existentes para a nova arquitetura.

Me deixe iniciar com algumas informações que podem surpreender. Primeiro, nenhum desses projetos usava as ferramentas padrão de planejamento de arquitetura de software. Nós não usamos UML, nem o modelo 4+1, nem ADR, nem o C4, tampouco diagramas de dependência. Nós criamos diversos diagramas, mas nenhum seguia estritamente alguma regra. Apenas os bons e velhos setas e caixas, similar a este que descreve informações de fluxo ou este que evidencia a estrutura das classes e os relacionamentos entre componentes. Era comum que dois diagramas dentro de um mesmo documento tivessem estruturas diferentes e eram comumente adicionados e alterados por engenheiros diferentes.

Segundo, não havia arquitetos nos times. Verdade seja dita, nem o Uber e nem o Skype/Microsoft têm posições específicas para arquitetos. Nessas empresas, é esperado que engenheiros de alto nível ainda façam codificação regularmente. Para todos os projetos, nós tínhamos engenheiros experientes envolvidos. No entanto, ninguém era detentor da arquitetura ou do projeto. Mesmo que esses desenvolvedores experientes liderassem o processo de design, os membros mais junior do time estavam envolvidos também, desafiando as decisões tomadas e sugerindo alternativas para serem discutidas.

Terceiro, nós tínhamos praticamente zero referências aos padrões de arquiteturas comuns e outros jargões utilizados na literatura da arquitetura de software, como o guia de arquitetura de Martin Fowler. Sem menções a micro serviços, serverless, fronteira de aplicação, arquitetura dirigida a eventos e tantas outras. Alguns desses conceitos surgiram durante os brainstormings. No entanto, não havia necessidade de referenciá-los nos documentos de design.

Design de software em empresas de tecnologia e startups

Então, como nós fizemos? E porque não seguimos nenhuma abordagem conhecida de arquitetura de software?
Tive essa discussão com engenheiros que trabalhavam em outras empresas de tecnologia - FANG (Facebook, Amazon, Netflix e Google) – e também em pequenas startups. A maioria dos times e projetos – pequenos e grandes – partilhavam uma abordagem similar de design e implementação.

Comece com o problema do negócio. O que estamos tentando resolver? Quais produtos estamos tentando desenvolver e porquê? Como podemos medir o sucesso?

Faça brainstorm da abordagem. Reúna-se com o time várias vezes para descobrir qual solução irá funcionar. Mantenha esses brainstorms pequenos. Comece em alto nível e desça aos níveis mais baixos.

Desenhe a abordagem. Junto ao time escolha uma pessoa para desenhar a abordagem para qual o time está convergindo. Vocês devem ser capazes de explicar, facilmente, a arquitetura do sistema/aplicativo em uma lousa. Iniciando pelo alto nível e se aprofundando quando for necessário. Se vocês tiverem problemas com essa explicação ou caso ela não esteja clara o suficiente, é necessário trabalhar mais nos detalhes.

Escreva a documentação de forma simples com diagramas simples baseado no que vocês explicaram em lousa. Mantenha o mínimo de jargões possíveis. Vocês vão querer que mesmo engenheiros junior entendam do que se trata. Escreva o documento com linguagem clara e fácil de entender. Na Uber, nós usamos um documento parecido com RFC com um template básico.

Fale sobre escolhas e alternativas. Bom design de software e boa arquitetura se resumem a fazer as escolhas corretas. Nenhum design é bom ou ruim por si só; tudo depende do contexto e dos objetivos. Sua arquitetura se divide em diferentes serviços? Diga porque vocês decidiram isso em vez de um serviço grande, que pode ter outros benefícios, como deploy mais direto e rápido. Vocês escolheram estender um serviço ou módulo com novas funcionalidades? Compare com a opção de desenvolver um serviço ou módulo separado e quais são os prós e contras que esta abordagem pode ter.

Circule o documento de design dentro dos times/organização para obter feedback. No Uber, nós enviávamos nosso documento de design para todos os engenheiros, na época nós éramos em torno de 2000. Agora que somos bem mais, ainda distribuímos bem amplamente nosso documento, mas começamos a nos atentar mais à relação de sinal/ruído. Encoraje as pessoas a perguntarem e oferecerem alternativas. Sejam pragmáticos em definir prazos, para discutir os feedbacks e incorporá-los, onde for necessário. O feedback direto pode ser rapidamente abordado no local, enquanto um feedback mais detalhado pode ser mais rápido para se estabelecer pessoalmente.

Porque nossa abordagem foi diferente do que é comumente escrito na literatura da arquitetura de software? Na verdade, nossa abordagem não é tão diferente assim, a princípio, da maioria dos manuais de arquitetura. Quase todos os guias sugerem iniciar com o problema de negócio e evidenciar as soluções e escolhas: que é o que fazemos. O que não fazemos é utilizar muitas das ferramentas complexas que muitos arquitetos e livros defendem. Nós documentamos o design o mais simples que conseguimos usando ferramentas diretas como Google Docs ou Office365.

Acredito que a grande diferença na nossa abordagem reside na cultura de engenharia dessas empresas. Alta autonomia e pouca hierarquia é um traço que empresas de tecnologia e startups compartilham; algo que as vezes não é verdade em empresas mais tradicionais. Essa é a razão pela qual esses lugares realizam muito mais “design baseado em senso comum” do que design dirigido por processos, com regras restritas.

Sei de bancos e empresas automotivas onde os desenvolvedores são ativamente desencorajados a tomarem decisões de arquitetura sem escalá-las, obtendo aprovação de arquitetos alguns níveis acima, que são responsáveis por acompanhar vários times. O processo se torna mais lento e os arquitetos podem ficar sobrecarregados com as demandas. Então esses arquitetos criam mais documentos formais, na esperança de tornar o sistema mais limpo, utilizando muito mais as ferramentas comuns que a literatura descreve. Esses documentos reforçam a ideia de hierarquia, já que é mais intimidador para o engenheiro, que não é um arquiteto, a questionar ou desafiar as decisões que já foram tomadas e documentadas usando métodos formais nos quais ele não está ambientado. Então ele geralmente não tenta. Para ser honesto, essas mesmas empresas querem otimizar os desenvolvedores tornando-os recursos intercambiáveis, permitindo-as a realocar as pessoas em diferentes projetos em curto prazo. Não deveria ser surpresa que diferentes ferramentas trabalhem melhor em ambientes diferentes.

Design de software simples e sem jargão em vez de padrões de arquitetura

O objetivo em desenhar um sistema deve ser a simplicidade. Quanto mais simples o sistema, mais simples é para entende-lo, para encontrar problemas nele e para implementá-lo. Quanto mais clara for a linguagem para descrevê-lo, mais acessível é seu design. Evite utilizar jargões que não são de entendimento de todos os membros da equipe: a pessoa com menos experiência deve ser capaz de entender igualmente às demais.

Design limpo é como código limpo: é fácil de ler e compreender. Existem muitos jeitos ótimos para escrever código limpo. No entanto, raramente você encontrará alguém sugerindo que você deve começar seu código aplicando padrões de projeto do GOF. Código limpo inicia-se com responsabilidade única, nomes claros e convenções fáceis de entender. Esses princípios aplicam-se à arquitetura limpa.

Então, qual o papel dos padrões de arquitetura? Vejo-os de forma similar à utilidade dos padrões de projeto de código. Podem dar ideias de como melhorar seu código ou sua arquitetura. Para padrões de código, eu enxergo singleton quando vejo um e levanto minha sobrancelha e escavo mais quando vejo uma classe que age como uma facade apenas realizando chamadas. Mas ainda não consigo imaginar “isso pede por uma abstract factory”. Na verdade, me levou muito tempo para entender o que esse padrão faz para ter meu momento “aha!”, depois de trabalhar muito com injeção de dependência – uma das poucas áreas onde esse padrão é, de fato, muito comum e útil. Devo admitir também que, apesar de ter passado muito tempo na leitura e compreensão dos padrões de projeto do GOF, eles tiveram um impacto menor em me tornar um desenvolvedor melhor do que os feedbacks que recebi de outros engenheiros.

Ao mesmo tempo, conhecer sobre padrões de arquitetura comuns é algo bom: ajuda a encurtar os debates com pessoas que os entendem da mesma forma que você. Porém, padrão de arquitetura não é o objetivo e não vai substituir designs simples de sistemas. Quando projetar um sistema, você pode se encontrar na situação de acidentalmente aplicar um padrão dos famosos, e isso é algo bom. Mais tarde você poderá referenciar sua abordagem mais facilmente. Mas a última coisa que você quer fazer é pegar um ou mais desses padrões e utilizá-los como martelo procurando pregos para pregar.

Os padrões de arquitetura nasceram depois que engenheiros observaram quão similar eram as escolhas feitas em alguns casos e como eram implementadas de forma similar. Elas foram então nomeadas, escritas e debatidas extensivamente. Padrões de arquitetura são ferramentas que vem depois que uma solução foi criada, na esperança de facilitar a vida de todos. Como um engenheiro, seu foco deve ser resolver problemas e aprender com eles em vez de pegar um padrão de arquitetura lindo e cheiroso na esperança de que ele resolva todos os seus problemas.

Melhores práticas de arquitetura de software, padrões de arquitetura corporativas e jeitos formais de descrever sistemas são ferramentas importantes para se conhecer e podem se tornar úteis eventualmente. Mas, quando estiver projetando um sistema, comece de forma simples e tente manter a simplicidade o quanto for possível. Tente evitar a complexidade que arquiteturas mais formais tendem a introduzir automaticamente.