Artigo original: Clean Code Explained – A Practical Introduction to Clean Coding for Beginners

"Qualquer um consegue escrever código que um computador entende. Bons programadores escrevem código que humanos entendem."                                       – Martin Fowler

Escrever código limpo, fácil de entender e que não dê dor de cabeça para mexer depois é essencial para qualquer programador.

Neste guia prático, vamos desvendar os segredos do código elegante e mostrar como deixar seu código tinindo!

Dando nome aos bois (ou melhor, às variáveis)

"Só existem duas coisas difíceis em Ciência da Computação: invalidar o cache e dar nomes às coisas."                                                                                                                – Phil Karlton

Já imaginou ter que decorar um monte de números sem sentido para usar um programa? É por isso que damos nomes às variáveis: para facilitar a nossa vida!

Um bom nome já diz tudo sobre a variável, sem precisar de gambiarras.

Nomes que contam uma história

Evite usar comentários para explicar o óbvio. Se o nome precisa de legenda, é hora de repensar a vida (e o código!).

"Um bom nome já diz para que ele serve, o que faz e como usar. Se precisa de comentário, é porque está faltando informação."                 – Clean Code

Jeito tosco:

var d; // tempo decorrido em dias

Não caia na armadilha de esconder o problema com comentários! Letras soltas, como x, y, a ou b só servem para confundir.

Jeito elegante:

var tempoDecorridoEmDias;
var diasDesdeACriacao;
var diasDesdeAModificacao;

Veja a diferença! Agora, sabemos exatamente o que cada variável guarda.

Informação clara e direta

Cuidado com nomes que induzem ao erro! Não chame um grupo de contas de listaDeContas se não for uma lista de verdade.

Seja específico e use nomes simples e diretos.

Jeito tosco:

var listaDeContas = [];

Jeito elegante:

var contas = []

Sem enrolação

Nomes longos e repetitivos só servem para ocupar espaço. Corte o excesso!

  • O ou A (como prefixo)
  • Informacoes
  • Dados
  • Variavel
  • Objeto
  • Gerenciador

Jeito tosco:

class InformacoesDoUsuario {
  // ...
}

Jeito elegante:

class Usuario {
  // ...
}

Falando a língua dos humanos

Escolha nomes fáceis de ler e pronunciar, para não ter que soletrar código em voz alta.

Jeito tosco:

const yyyymmdstr = moment().format("YYYY/MM/DD");

Jeito elegante:

const dataAtual = moment().format("YYYY/MM/DD");

Fácil de encontrar

Evite usar números mágicos no código. Dê nomes descritivos às constantes para facilitar a busca.

Jeito tosco:

if (aluno.aulas.length < 7) {
   // Fazer alguma coisa
}

Jeito elegante:

if (aluno.aulas.length < MAXIMO_AULAS_POR_ALUNO) {
    // Fazer alguma coisa
}

Agora, se precisarmos mudar o limite de aulas, é só ajustar a constante.

Consistência é a alma do negócio

Use o mesmo nome para o mesmo conceito em todo o código. Nada de usar buscar, recuperar e obter para a mesma operação!

Funções espertas e enxutas

Tamanho é documento

Funções curtas e diretas são mais fáceis de entender e manter. Evite escrever códigos gigantes!

Uma função, uma responsabilidade

Funções devem fazer apenas uma coisa, devem fazê-la bem e ponto final. – Clean Code

Se sua função está fazendo malabarismos, é hora de dividi-la em partes menores.

Escondendo a complexidade

Use funções para encapsular condições complexas e deixar o código principal mais limpo.

Exemplo:

public void inserirPeca(int coluna) throws Exception {
        if (jogadaValida(coluna)) {
            // Lógica para inserir a peça
        } else {
            // Lógica para lidar com jogadas inválidas
        }
    }

    private boolean jogadaValida(int coluna) {
        // Verificar se a coluna é válida e se a jogada é possível
    }

Argumentos contidos

Funções com muitos argumentos são confusas e difíceis de testar. Limite-se a dois, no máximo.

Evite as flags

Argumentos booleanos que controlam o fluxo da função são sinais de problemas. Divida a função em funções menores!

Efeitos colaterais: evite-os!

Efeitos colaterais são como surpresas desagradáveis no código. Evite modificar variáveis globais ou parâmetros passados por referência sem necessidade.

Repetição? Nem pensar!

Código duplicado é sinônimo de dor de cabeça. Use as ferramentas da sua IDE para extrair métodos e evitar repetições.

Dicas extras

Comentários não são lixeiras

Evite comentar código desnecessário. Se não for mais útil, exclua-o! Use o controle de versão para recuperar o código antigo, se precisar.

Conheça as regras do jogo

Cada linguagem tem suas próprias convenções de estilo. Use e abuse das boas práticas! Confira os guias de estilo abaixo (em inglês):

Conclusão

Código limpo é um hábito que se constrói com o tempo. Aplique esses princípios no seu dia a dia e veja a mágica acontecer!

Gostou do guia? Compartilhe-o com seus amigos programadores! 😉