Pausa para café #103. Em defesa do “Código Limpo”: 100 dicas atemporais

Fonte: Hackernoon “Clean Code” de Robert C. Martin é o livro de programação mais recomendado de todos os tempos. Pesquise livros usando a consulta “melhores livros para desenvolvedores de software” e é quase certo que você encontrará este livro nos resultados da pesquisa. E embora algumas pessoas sintam que não vale a pena prestar atenção ao Código Limpo, eu diria que tais sentimentos estão profundamente equivocados. Sim, alguns dos conselhos do livro são questionáveis. Sim, parte do conteúdo parece desatualizado. Sim, alguns exemplos são confusos. É tudo verdade. Mas não sejamos tão rápidos em descartar as muitas dicas úteis que este livro oferece! Ignorar completamente o Código Limpo simplesmente por causa de algumas ideias ruins não é a melhor solução. Então, sem mais delongas, vamos dar uma olhada nas melhores dicas que o Clean Code tem a oferecer! Analisaremos cada capítulo, resumindo as ideias que Tio Bob e seus coautores oferecem.

Capítulo 1: Código Limpo

1. A quantidade geral de desordem aumenta com o tempo.

2. Restaurar um sistema desatualizado do zero é muito difícil. Refatoração e melhorias incrementais serão a melhor opção para isso.

3. Em uma base de código confusa, tarefas que deveriam levar apenas algumas horas podem levar dias ou semanas para serem concluídas.

4. Aproveite o tempo para agir rapidamente.

5. O código limpo faz uma coisa bem. Código ruim tenta fazer muito.

6. O código limpo é bem testado.

7. Ao ler um código bem escrito, cada função faz aproximadamente o que você esperaria.

8. Se você discorda de um princípio ensinado por alguém com anos de experiência, você deveria pelo menos considerar o ponto de vista dele antes de ignorá-lo.

9. O código é lido com muito mais frequência do que escrito.

10. Código que é mais fácil de ler é mais fácil de alterar.

11. Deixe a base de código melhor do que quando a encontrou (Regra dos escoteiros).

Capítulo 2: O Significado dos Nomes

1. Escolha os nomes das variáveis ​​com cuidado.

2. Escolher bons nomes é difícil.

3. O nome de uma variável ou função deve indicar o que é e como é usada.

4. Evite usar nomes de variáveis ​​com um único caractere, exceto nomes comumente usados, como i para uma variável de contador em um loop.

5. Evite usar abreviações em nomes de variáveis.

6. Os nomes das variáveis ​​devem ser pronunciáveis ​​para que você possa falar sobre eles e dizê-los em voz alta.

7. Use nomes de variáveis ​​que sejam fáceis de encontrar.

8. Classes e objetos devem ter nomes na forma de substantivos.

9. Os nomes de métodos e funções devem ser verbos ou pares verbo-substantivo.

Capítulo 3: Funções

1. As funções devem ser pequenas.

2. A função deve executar uma ação.

3. As funções devem ter nomes descritivos.

4. Extraia o código no corpo if/else ou mude as instruções para funções claramente nomeadas.

5. Limite o número de argumentos que uma função aceita.

6. Se uma função exigir muitos argumentos de configuração, considere combiná-los em uma única variável de parâmetros de configuração.

7. As funções devem ser puras, o que significa que não apresentam efeitos colaterais e não modificam seus argumentos de entrada.

8. A função deve ser um comando ou uma consulta, mas não ambos ao mesmo tempo (Command Query Separation).

9. É melhor remover erros e exceções do código do que deixar erros no código.

10. Extraia código duplicado em funções claramente nomeadas (não se repita).

11. Os testes unitários facilitam a refatoração.

Capítulo 4: Comentários

1. Os comentários podem estar incorretos. Eles podem estar errados no início ou podem ser inicialmente precisos e depois ficarem desatualizados com o tempo à medida que o código muda.

2. Use comentários para descrever por que está escrito dessa maneira, em vez de explicar o que está acontecendo.

3. Muitas vezes, os comentários podem ser evitados usando variáveis ​​claramente nomeadas e extraindo seções de código em funções claramente nomeadas.

4. Prefixe comentários TODO com prefixos consistentes para torná-los mais fáceis de encontrar. Revise e limpe seus comentários TODO periodicamente.

5. Não use Javadocs apenas por usá-los. Comentários que descrevem o que um método faz, quais argumentos ele utiliza e o que ele retorna são redundantes, na melhor das hipóteses, e enganosos, na pior.

6. Os comentários devem incluir todas as informações relevantes e o contexto de que o leitor precisará. Não seja preguiçoso ao escrever um comentário.

7. Comentários de log e comentários do autor do arquivo não são necessários devido ao controle de versão e culpa do git.

8. Não comente o código morto. Apenas exclua-o. Se você acha que precisará do código no futuro, é para isso que serve o controle de versão.

Capítulo 5: Formatação

1. Em equipe, selecionem um conjunto de regras para formatar seu código e apliquem essas regras de forma consistente. Não importa com quais regras você concorde, você precisa chegar a um acordo.

2. Use formatação automática de código e um analisador de código. Não confie nas pessoas para encontrar e corrigir manualmente todos os erros de formatação. Isso é ineficiente, improdutivo e uma perda de tempo na revisão do código.

3. Adicione espaços verticais entre linhas de código para separar visualmente blocos de código relacionados. Tudo que você precisa é fazer uma nova linha entre os grupos.

4. Arquivos pequenos são mais fáceis de ler, entender e mover do que arquivos grandes.

5. As variáveis ​​devem ser declaradas perto de onde são usadas. Para funções pequenas, geralmente fica no topo da função.

6. Mesmo para funções curtas ou instruções if, formate-as corretamente em vez de escrevê-las em uma linha.

Capítulo 6: Objetos e Estruturas de Dados

1. Os detalhes de implementação em um objeto devem estar ocultos atrás da interface do objeto. Ao fornecer uma interface para uso pelos consumidores de um objeto, você torna mais fácil refatorar posteriormente os detalhes da implementação sem causar alterações significativas. Abstrações facilitam a refatoração.

2. Qualquer pedaço de código não deve ter conhecimento dos detalhes internos do objeto em que opera.

3. Ao trabalhar com um objeto, você deve exigir que ele execute um comando ou consulta, em vez de perguntar sobre seus componentes internos.

Capítulo 7: Corrigindo Erros

1. O tratamento de erros não deve interferir no restante do código do módulo.

2. É melhor remover erros e exceções do código do que deixar erros no código.

3. Escreva testes com erros para garantir que seu código os identifique e não os perca.

4. As mensagens de erro devem ser informativas, com todo o contexto necessário que alguém possa precisar para solucionar o problema de maneira eficaz.

5. Agrupar APIs de terceiros em uma fina camada de abstração facilita a substituição de uma biblioteca por outra no futuro.

6. Agrupar APIs de terceiros em uma fina camada de abstração facilita a simulação da biblioteca durante os testes.

7. Use o padrão Caso Especial ou Objeto Nulo para lidar com comportamento excepcional, como quando determinados dados não existem.

Capítulo 8: Limites

1. Bibliotecas de terceiros ajudam a acelerar a entrega de produtos, permitindo terceirizar várias tarefas.

2. Escreva testes para garantir que você está usando a biblioteca de terceiros corretamente.

3. Use o padrão do adaptador para preencher a lacuna entre a API de uma biblioteca de terceiros e a API que você gostaria de ter.

4. Agrupar APIs de terceiros em uma fina camada de abstração facilita a substituição de uma biblioteca por outra no futuro. (Repita do Capítulo 7)

5. Agrupar APIs de terceiros em uma fina camada de abstração facilita a simulação da biblioteca durante os testes. (Repita do Capítulo 7)

6. Tente não fornecer muitas informações ao seu aplicativo sobre os detalhes de qualquer biblioteca de terceiros.

7. É melhor depender daquilo que você controla do que daquilo que você não controla.

Capítulo 9: Testes Unitários

1. O código de teste deve ser tão limpo quanto o código de produção (com algumas exceções, geralmente relacionadas à memória ou eficiência).

2. À medida que o código de produção muda, o código de teste também muda.

3. Os testes ajudam a manter seu código de produção flexível e de fácil manutenção.

4. Os testes permitem que você faça alterações, permitindo refatorar com confiança, sem medo de não perceber.

5. Estruture seus testes usando o padrão Arrange-Act-Assert (também conhecido como Build-Operate-Check, Setup-Exercise-Verify ou Given-When-Then).

6. Use funções específicas do domínio para facilitar a escrita e a leitura dos testes.

7. Pontue um conceito por teste.

8. Os testes devem ser rápidos.

9. Os testes devem ser independentes.

10. Os testes devem ser repetíveis.

11. Os testes não devem exigir confirmação.

12. Os testes devem ser escritos em tempo hábil, pouco antes ou depois da escrita do código de produção, e não meses depois.

13. Se seus testes forem ruins, espere que haja bugs em seu código.

Capítulo 10: Aulas

1. As turmas devem ser pequenas.

2. As turmas devem ser responsáveis ​​apenas por uma coisa e devem ter apenas um motivo para mudar (princípio da responsabilidade única).

3. Se você não conseguir definir um nome claro para a classe, provavelmente ela é muito grande.

4. Seu trabalho não termina quando você faz um trecho de código funcionar. A próxima etapa será refatorar e limpar o código.

5. Usar muitas classes pequenas em vez de várias classes grandes em seu aplicativo reduz a quantidade de informações que um desenvolvedor deve compreender ao trabalhar em qualquer tarefa.

6. Ter um bom conjunto de testes permite refatorar com confiança ao dividir classes grandes em classes menores.

7. As aulas devem ser abertas para extensão, mas fechadas para modificação (princípio aberto-fechado).

8. Interfaces e classes abstratas criam costuras que facilitam os testes.

Capítulo 11: Sistemas

1. Use injeção de dependência para dar aos desenvolvedores a flexibilidade de passar qualquer objeto com a interface apropriada para outra classe.

2. Use injeção de dependência para criar interfaces entre objetos em seu aplicativo para facilitar os testes.

3. Os sistemas de software não são como um edifício que precisa ser projetado antecipadamente. São mais como cidades que crescem e se expandem ao longo do tempo, adaptando-se às necessidades atuais.

4. Adie a tomada de decisão até o último momento crítico.

5. Use uma linguagem específica do domínio para que os especialistas e desenvolvedores do domínio usem a mesma terminologia.

6. Não complique demais o seu sistema. Use a coisa mais simples que funciona.

Capítulo 12: Implantação

1. Os sistemas que não podem ser testados não podem ser verificados e os sistemas que não podem ser verificados nunca devem ser implantados.

2. Escrever testes leva a um design melhor porque o código fácil de testar geralmente usa injeção de dependência, interfaces e abstração.

3. Um bom conjunto de testes eliminará o medo de quebrar seu aplicativo durante a refatoração.

4. A duplicação de código cria mais riscos porque há mais locais no código que podem ser alterados e ainda mais locais onde os erros podem ser ocultados.

5. O código que você escreve agora é mais fácil de entender porque você está profundamente envolvido em entendê-lo. Não é fácil para outros atingirem rapidamente o mesmo nível de compreensão.

6. A maior parte do custo de um projeto de software está relacionada à manutenção de longo prazo.

7. Os testes servem como documentação viva de como seu aplicativo deve (e se comporta) se comportar.

8. Não prossiga quando seu código funcionar. Aproveite o tempo para torná-lo mais claro e compreensível.

9. A próxima pessoa a ler seu código em um futuro próximo provavelmente será você. Seja gentil com você mesmo no futuro, escrevendo códigos fáceis de entender.

10. Resista ao dogma. Abrace o pragmatismo.

11. Leva décadas para se tornar um engenheiro de software realmente bom. Você pode acelerar sua curva de aprendizado aprendendo com os especialistas ao seu redor e aprendendo os padrões de design comumente usados.

Capítulo 13: Paralelismo

1. Escrever código paralelo é difícil.

2. Bugs e problemas ocasionais difíceis de reproduzir geralmente são problemas de simultaneidade.

3. O teste não garante que seu aplicativo estará livre de bugs, mas minimizará o risco.

4. Aprenda sobre problemas comuns de simultaneidade e suas possíveis soluções.

Capítulo 14: Refinamento Sequencial

1. O código limpo geralmente não começa do zero. Você escreve uma solução aproximada primeiro e depois a refatora para torná-la mais limpa.

2. É um erro parar de trabalhar no código depois que ele começa a funcionar. Aproveite o tempo para torná-lo ainda melhor depois que já estiver funcionando.

3. A agitação está crescendo gradualmente.

4. Se você se encontrar em uma situação difícil em que adicionar recursos é muito difícil ou demora muito, pare de escrever recursos e comece a refatorar.

5. A mudança incremental é muitas vezes melhor do que reconstruir do zero.

6. Use o Desenvolvimento Orientado a Testes (TDD) para fazer um grande número de alterações muito pequenas.

7. Um bom design de software envolve separar as preocupações em seu código e separar o código em módulos, classes e arquivos menores.

8. É mais fácil limpar uma bagunça imediatamente depois de feita do que depois.

Capítulo 15: Internos do JUnit

1. Nomes de variáveis ​​negativas ou expressões condicionais são um pouco mais difíceis de entender do que nomes positivos.

2. A refatoração é um processo iterativo cheio de tentativa e erro.

3. Deixe a base de código melhor do que quando a encontrou (Regra dos escoteiros). (Repetido do Capítulo 1)

Capítulo 16: Refatorando SerialDate

1. Revisões de código e críticas ao nosso código nos tornam melhores, e devemos acolher isso.

2. Primeiro faça o código funcionar e depois corrija-o.

3. Nem toda linha de código precisa de teste.

Capítulo 17: Cheiros e Heurísticas

1. O código limpo não é um conjunto de regras, mas sim um sistema de valores que determinam a qualidade do seu trabalho.

[Neste capítulo, Tio Bob lista mais 66 variações de seu código e heurística, muitas das quais foram abordadas no restante do livro. Reproduzi-los aqui seria essencialmente copiar e colar o nome de cada item, por isso evitei fazer isso. Eu sugiro que você leia o livro!]

Conclusão

Vamos terminar onde começamos: Clean Code de Robert C. Martin é o livro de programação mais recomendado de todos os tempos. Há uma boa razão para isso.