No mundo ideal, o criador de um determinado sistema ou aplicação seria o responsável por sua manutenção e atualização futura. Entretanto, no mundo prático isso não é possível: profissionais mudam de posição, de empresa ou até de carreira o tempo todo. O resultado disso é que, muito provavelmente, boa parte dos desenvolvedores irá passar uma parte significativa da sua rotina ao lado de um código que não escreveu. Comentários e documentação acabam se tornando ferramentas essenciais para decifrar a mente do profissional que veio antes.
Da mesma forma, é quase certo que o seu código, algum dia, será o desafio de outro desenvolvedor. Atalhos tomados, decisões feitas, técnicas ousadas ou mesmo a boa e velha “gambiarra” podem se tornar obstáculos para mentes que não pensam como a sua.
Yang Zhou é um engenheiro sênior Full Stack, que mora na Inglaterra e escreve sobre Python, JS e programação em geral. Em um artigo publicado na internet, ele explica que é fácil escrever código que funciona, mas escrever código que seja legível para outros desenvolvedores pode ser muito mais complexo.
Com sua autorização, traduzimos e reproduzimos o artigo na íntegra:
“Joel Spolsky, o fundador do Stack Overflow, tem um ditado famoso: ‘é mais difícil ler o código do que escrevê-lo’.
Infelizmente, é verdade. Ler o código de outras pessoas é nosso trabalho diário como engenheiros de software. Se você trabalha como engenheiro por muito tempo, provavelmente já ficou chateado com algum código mal legível ou mesmo ilegível.
Este artigo resume os 10 sintomas comuns de código ilegível. A ambição deste artigo não é apenas lembrá-lo de evitar essas más práticas. Mais importante, quero que você saiba que quando você lê ou depura algum código insustentável e fica bravo, você não está sozinho 🙂. Porque resumi essas 10 questões com base na minha experiência real. Cada uma dessas coisas, umas mais, outras menos, me encontrou e me enlouqueceu antes.
1) Sem comentários
A maneira mais fácil de tornar um bloco de código mais compreensível é adicionar alguns comentários para explicá-lo. No entanto, para iniciantes, escrever código é divertido, mas escrever comentários pode não ser. Mas o problema é que, depois de alguns dias, o mesmo código pode ficar ilegível até para quem o escreveu.
2) Muito código comentado
Comentar algum código existente e verificar os resultados é um método muito útil para depuração. Mas após a depuração, especialmente antes de enviar o código para um repositório remoto, devemos nos lembrar de deletar o código comentado. Porque todos os membros da equipe atualizarão sua base de código a partir do repositório remoto e provavelmente ficarão confusos e aborrecidos se houver muitos códigos comentados
3) Muitos Números Mágicos
Meses atrás, encontrei um pedaço de código Javascript parecido com o seguinte:
for (let i=0; i<5; i++){
// faz alguma coisa
}Eu não tinha ideia ao que se referia o número mágico “5”. Para piorar a situação, o colega que escreveu esse código havia saído da empresa. 😭
Depois de muitos palpites e tentativas, finalmente descobri.
Para ser sincero, se esse cara ainda estivesse disponível, eu definitivamente o deixaria alterar o código da seguinte maneira:
const maxOptions = 5;
for (let i=0; i < maxOptions; i++){
// faz alguma coisa
}4) Nomes sem sentido
Embora isso possa soar como um truísmo, ainda vale a pena mencionar as questões de nomenclatura.
Um bom nome para uma variável, classe ou função deve ser claro e autodescritivo. Se um nome for bom o suficiente para descrever qual é a variável correspondente, não há necessidade de adicionar comentários extras.
5) Muito longo para ler
Se você abrir um script e houver mais de 5.000 linhas de código nesse único arquivo, qual palavra você dirá? 😄
Mas quão longo é muito longo? De um modo geral, quando há quase 800 linhas de código em um arquivo, devemos começar a pensar em separar diferentes funções em mais arquivos.
6) Muito curto para ler
O código curto parece legal, mas pode nem sempre ser legível.
Por exemplo, o seguinte código Python de uma linha define uma função que pode receber um número “N” e retornar o N-ésimo número de Fibonacci:
fib = lambda x: x if x<=1 else fib(x-1) + fib(x-2)
É curto, elegante e bacanudo. Podemos tentar da seguinte forma:
for i in range(1, 10):
print(fib(i),end=' ')
# 1 1 2 3 5 8 13 21 34No entanto, não recomendo que você escreva código dessa maneira para software sério. Afinal, ser fácil de ler é mais importante do que ser bacanudo. Em outras palavras, ser fácil de ler é bacanudo.
7) Acopla várias funções juntas
Se uma função for escrita para muitas operações, ela será muito longa para ser lida. Sem mencionar que é difícil modificá-la. Nesse caso, o princípio da responsabilidade única é realmente uma regra de ouro. Simplificando, cada função, classe ou módulo deve ser responsável por apenas uma coisa.
Uma classe deve ter apenas um motivo para mudar
Robert C. Martin
8) Design de classes confuso
A programação orientada a objetos é um grande tópico. Compreender e aplicar a filosofia de design de classes não é fácil. Certa vez, conheci um projeto com design de classes ruim. Levei muito esforço apenas para resolver o relacionamento de herança entre as classes.
Quando um projeto se torna cada vez maior, o relacionamento entre as diferentes classes pode ser cada vez mais complexo. Nesse caso, o princípio SOLID é a melhor prática para programação orientada a objetos.
9) Implementa a mesma coisa várias vezes
Existe um velho ditado no mundo da programação: ‘não repita a si mesmo’. Se você entender totalmente o objetivo dessa máxima, sua vida de engenheiro será mais fácil.
Vamos pensar em uma pergunta simples: por que um programador se preocupa em repetir? Mais especificamente, se já existe uma função semelhante, por que um programador deseja implementar outra?
Duas razões possíveis:
- O programador não está muito familiarizado com a base de código e não conhece a função semelhante.
- A função anterior foi escrita por outros. Como é mais difícil ler o código do que escrevê-lo, o programador simplesmente não se preocupa em lê-lo e usá-lo.
Portanto, se você é responsável por um projeto de software e um novo desenvolvedor acaba de ingressar em sua equipe, dê a ele tempo suficiente para se familiarizar com o código existente. É bom para todos os membros da sua equipe.
10) Sem manipuladores de exceção
Quando eu era um novato, nunca quis escrever coisas sobre manipulação de exceções. Porque eu pensei que faria meus programas parecerem feios. Eu estava absolutamente errado.
Por um lado, os manipuladores de exceção são super úteis para encontrarmos bugs ocultos, especialmente para código assíncrono. Por outro lado, eles podem lembrar aos leitores que os locais correspondentes são propensos a erros, o que melhora muito a legibilidade do código.
Conclusão
Escrever código funcional é fácil, mas escrever código legível é difícil. Um grande desenvolvedor não é aquele que escreve códigos muito sofisticados que ninguém consegue entender. Um grande desenvolvedor é aquele que implementa um software complexo por meio de um código simples e legível.”
Publicado originalmente como “10 Common Symptoms of Unreadable Code” em 8 de julho de 2021. Traduzido e republicado com autorização do autor.
