CLEAN CODE
1 Capítulo - Nomes Significativos
Use Nomes Que Revelem Seu Propósito:
Os nomes devem demostrar seu propósito é fácil.
Evite Informações Erradas:
Devemos evitar palavras cujos significados podem se desviar
daquele que desejamos.
Faça Distinções Significativas:
Faça a distinção dos nomes de uma forma que o leitor
compreenda as diferenças.
Use Nomes Pronunciáveis:
Crie nomes pronunciáveis
Use Nomes Passiveis De Busca:
Nomes de uma só letra ou números possuem um problema em
particular por não ser fácil localiza-lo ao longo de um texto.
Interfaces E Implementações:
Prefiro não enfeitar as interfaces. O “i” no início, tão comum no
hoje em dia, é na melhor hipótese uma distração, e na pior são
informações excessivas.
Nomes De Classes:
Classes e objetos devem ter nomes com substantivo(S) e
também não deve ser um verbo.
Nomes De Métodos:
Os nomes de métodos devem ter verbos.
Não Faça Trocadilhos:
Evite usar a mesma palavra para dois propósitos. Usar o mesmo
termo para duas ideias diferentes é basicamente um trocadilho.
Use Nomes A Partir Do Domínio Da Solução:
Usar termos de informática, nomes de algoritmos, nomes de
padrões, termos matemáticos, etc.
Adicione Um Contexto Significativo:
Usar nomes que façam parte do contexto para o leitor. Para isso,
você os coloca em classes, funções e namespaces bem
nomeados.
2 Capítulo – Funções
Pequenas:
A primeira regra para funções é que elas devem ser pequenas.
Use Nomes Descritivos:
Descreve o que a função faz. Escolher bons nomes para funções
pequenas que fazem apenas uma coisa.
Quando menor e mais centralizada for a função, mais fácil será
pensar em um nome descritivo.
Um nome longo e descritivo é melhor do que um comentário
extenso e descritivo.
Parâmetros De Funções:
A quantidade ideal de parâmetros para uma função é zero (nulo).
Formas Mônades Comuns:
Você deve escolher nomes que tornem claras a distinção, e
sempre use duas formas em um contexto consistente. Uma forma
menos comum mais ainda bastante útil de um parâmetro para
uma função é um evento.
Parâmetros Lógicos:
Esses parâmetros são feios. Passar um booleano para uma
função certamente é uma pratica horrível, pois ele complica
imediatamente a assinatura do método, mostrando explicitamente
que a função faz mais de uma coisa. Ela faz uma coisa se o valor
for verdadeiro, e outra se for falso.
Funções Díades:
Uma função com dois parâmetros é mais fácil de entender do que
uma com um (mônade).
Díades não são ruins, e você certamente terá de usa-las.
Entretanto, deve-se estar ciente de que haverá um preço a pagar
e, portanto, deve-se pensar em tirar proveito dos mecanismos
disponíveis a você para convertê-los em mônades.
Tríades:
Funções que recebem três parâmetros são consideravelmente
mais difíceis de entender do que as díades. A questão de
ordenação, pausa e ignoração apresentam mais do que o dobro
de dificuldade. Sugiro que você pense bastante antes de criar
uma tríade.
Objetos Como Parâmetros:
Quando uma função parece precisar de mais de dois os três
parâmetros, é provável que alguns deles podem ser colocados
em uma classe própria.
Verbos E Palavra-Chave:
Escolher bons nomes para funções pode ir desde explicar o
proposito da função a ordem e a finalidade dos parâmetros. No
caso de uma mônade, a função e o parâmetro devem formar um
belo par verbo/substantivo.
Extraia Os Blocos Try/Catch:
Esses blocos são feios por si só. Eles confundem a estrutura do
código e misturam o tratamento de erro com o processamento
normal do código. Portanto, é melhor colocar as estruturas try e
catch em suas próprias funções.
Tratamento De Erros É Uma Coisa Só:
Tratamento de erro é uma coisa só. Portanto, uma função que
trata de erros não deve fazer mais nada.
Evite Repetição:
Duplicação é um problema, pois ela amontoa o código e serão
necessárias quatro modificação se o algoritmo mudar. Além de
serem quatro oportunidades para a omissão de um erro.
3 Capítulo – Comentários
Comentários Compensam Um Código Ruim:
Uma das motivações mais comuns para criar comentários é um
código ruim.
Comentários Bons:
Tenha em mente, contudo, que o único comentário
verdadeiramente bom é aquele em que você encontrou uma
forma para não escrevê-lo.
Comentários Legais:
Frases sobre direitos autorais e autoria são informações
necessárias e logicas para se colocar no inicio de um arquivo
fonte.
Comentários Informativos:
Ás vezes é prático fornecer informações básicas em um
comentário.
Um comentário como este pode ser útil as vezes, mas, sempre
que possível, é melhor usar o nome da função para transmitir a
informação.
Explicação Da Intenção:
Ás vezes, um comentário vai além de ser apenas informações
uteis sobre a implementação e fornece a intenção por trás de uma
decisão.
Esclarecimento:
As vezes é bom traduzir o significado de alguns parâmetros ou
valores retornados obscuros para algo inteligível.
É melhor encontrar uma forma de esclarecer tal parâmetro ou
valor retornado por si só, mas quando for parte da biblioteca
padrão, ou de um código que não se possa alterar, então um
comentário esclarecedor pode ser útil.
Alerta Sobre Consequências:
Ás vezes é útil alertar outros programadores sobre certas
consequências.
Comentário TODO:
Ás vezes é cabível deixar notas “To Do” (“Para Fazer”) em
comentários no formato //TODO.
TODOS são tarefas que os programadores acham que devem ser
efetuadas, mas, por alguma razão, não podem no momento.
Pode ser um lembrete para excluir uma instrução desnecessária
ou um apelo para que alguém olhe o problema. Ou um pedido
para que alguém pense em um nome melhor ou um lembrete
para fazer uma alteração que é dependente de um evento
determinado.
Destaque:
Pode-se usar um comentário para destacar a importância de algo
que talvez pareça irrelevante.
Comentários Enganadores:
Ás vezes, com todas as melhores das intenções, um programador
faz uma afirmação não muito clara em seus comentários.
Comentários Longos:
Comentários extensos são apenas entulhos que confundem o
código, devendo assim ser completamente removidos.
Comentários Ruidosos:
Ás vezes você vê comentários que nada são além de “chiados”.
Eles dizem o obvio e não fornecem novas informações.
Troque a tentação para criar ruídos pela determinação para
limpar seu código. Você perceberá que isso lhe tornará um
programador melhor e mais feliz.
Comentários Ao Lado De Chaves De Fechamento:
Ás vezes, os programadores colocam comentários especiais ao
lado de chaves de fechamento.
Portanto, se perceber uma vontade de comentar ao lado de
chaves de fechamento, tente primeiro reduzir suas funções.
Créditos E Autoria:
Não há necessidade de poluir o código com comentários de
autoria.
Códigos Como Comentários:
Poucas praticas são tão condenáveis quanto colocar o código
como comentário. Não faça isso!
Comentários HTML:
Códigos HTML em comentários de código fonte são uma
aberração. Eles dificultam a leitura dos comentários onde seriam
fáceis de ler.
Informações Não-Locais:
Se você precisar escrever um comentário, então, coloque-o perto
do código que ele descreve. Não forneça informações gerais do
sistema no contexto de um comentário local.
Informações Excessivas:
Não adicione discussões históricas interessantes ou descrições
irrelevantes de detalhes em seus comentários.
Conexões Nada Obvias:
A conexão entre um comentário e o código que ele descreve deve
ser óbvia.
Cabeçalhos De Funções:
Funções curtas não requerem muita explicação. Um nome bem
selecionado para uma função pequena que faça apenas uma
coisa costuma ser melhor do que um comentário no cabeçalho.
