Olá! Para os insights de código limpo desta semana resolvi trazer algumas passagens do capítulo sobre comentários e então deixar meus 50 centavos sobre cada passagem. O capítulo inicia com a seguinte frase:
“Não comente código ruim. Reescreva-o.”
~ Brian W. Kernigham e P. J. Plaugher
Interessante, não? Pare para pensar… melhor reescrever um código para que ele seja entendido, do que colocar um comentário para tentar explicar um código ruim.
“Comentários são um mal necessário”
~ Tio Bob
Aqui Bob explica que o ideal é que os comentários sejam evitados, mas que em alguns casos serão necessários. Veremos alguns casos em seguida.
“O uso adequado de comentários serve para compensar nossa falha em nos expressarmos através do código.”
~ Tio Bob
Se um código é realmente legível, com uma boa estrutura e bons nomes de funções a variáveis, pra que comentários? Pense sobre isso.
“Quando você se encontrar em uma posição onde você precisa escrever um comentário, pense sobre isso e veja se não há alguma maneira de virar a mesa e se expressar no código.
~ Tio Bob
Faz sentido, não?
Bob se pergunta:
“Porquê sou tão contra os comentários? Por que eles mentem.”
~ Tio Bob
Comentários nem sempre mentem e nem sempre isso é intencional, mas com frequência isso ocorre, por isso, cuidados precisam ser tomados.
“A verdade só pode ser encontrada em um lugar: o código. Somente o código pode verdadeiramente lhe dizer o que ele faz.”
~ Tio Bob
Ou seja, um comentário, por mais bem escrito, não irá lhe dizer exatamente o que o código faz. Códigos bem escritos se explicam por si só.
“Em vez de perder seu tempo escrevendo os comentários que explicam a bagunça que você fez, invista tempo em limpar essa bagunça.”
~ Tio Bob
Profissionais de desenvolvimento de software devem se preocupar com o código que escrevem, pois provavelmente, este terá que ser mantido por seus colegas, portanto, não tente explicar códigos ruins com comentários, em vez disso, tente escrevê-los de uma maneira melhor.
Veja os seguintes códigos (com e sem comentário, respectivamente):
// Check to see if the employee is eligible for full benefits if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
if (employee.isEligibleForFullBenefits())
“Na maioria dos casos é simplesmente uma questão de criar uma função que diz exatamente a mesma coisa que o comentário que você quer escrever.”
~ Tio Bob
Não ficou muito mais claro o segundo código do que o primeiro? A escrita de funções para a realização de tarefas específicas simplifica muito a leitura de código.
“TO-DO’s” são tarefas que os programadores pensam que precisariam ser feitas, mas que por alguma razão não podem ser feitas nesse exato momento.
Portanto, procure-os regularmente e elimine os que você puder.”
~ Tio Bob
Acho que ficou bem claro né.
“Se você decidir escrever um comentário, então invista o tempo para ter certeza que é o melhor comentário que você pode escrever.”
~ Tio Bob
Já que os comentários são um mal necessário, pense bem antes de escreve-los, faça-os quando são realmente necessários, e faça-os bem.
“Algumas pessoas adicionam comentários para iniciar um módulo a toda hora que o editam. Estes comentários se acumulam como um tipo de jornal, ou log de cada mudança que foi feita.
Um tempo atrás haviam boas razões para se criar e manter esse tipo de entradas no log… Nós não tínhamos sistema de controle de versão de código para fazer isso por nós. Hoje em dia, no entanto, estes jornais longos servem apenas para confundir e ofuscar o módulo. Eles devem ser completamente removidos.”
~ Tio Bob
Viva o git!!!
“Não use um comentário quando você pode usar uma função ou uma variável”
~ Tio Bob
É o mesmo caso do código para verificar se o empregado é elegível para todos os benefícios. Bons nomes de funções e variáveis evitam a necessidade de comentários.
“Os sistemas de controle de versão de código são muito bons em lembrar quem adicionou o quê e quando. Não existe a necessidade de poluir o código com assinaturas.”
~ Tio Bob
Deixe que o git ou sua ferramenta de controle de versão de código favorita tome conta de registrar o que foi feito, por quem e quando, seu código não necessita de sua assinatura.
“Poucas práticas são tão odiadas como código comentado. Não faça isso!”
~ Tio Bob
Código comentado gera confusão e nunca são recomendados.
“Se você precisa escrever um comentário, tenha certeza que ele descreve o código que aparece perto dele. Não ofereça informação fora do contexto de um comentário local.”
~ Tio Bob
O recado aqui é: não se deve adicionar comentários em código que explicam partes do código que não estão no contexto. Casos como esse geram grandes probabilidades de comentários se tornarem desatualizados e gerarem confusão.
“Não coloque discussões históricas interessantes ou descrições de detalhes irrelevantes em seus comentários.
~ Tio Bob
Ou seja, não escreva comentários como este:
“O propósito de um comentário é explicar código que não é auto-explicável. É uma pena quando um comentário precisa de sua própria explicação.”
Tio Bob
Comentário que precisa de explicação não faz sentido. Invista na escrita dos comentários quando eles são realmente necessários, isso já foi dito antes.
“Um boa escolha de nome para uma função pequena que faz uma coisa é normalmente melhor do que um comentário de cabeçalho.”
~ Tio Bob
Também já falamos sobre como bons nomes evitam a necessidade de comentários, portanto, não vou me estender aqui.
Por hoje é isso. Achou interessante? Recomendo a leitura do livro original.
Quer conversar a respeito? Deixe um comentário 😛
E tenha uma ótima semana!!
TALKING ABOUT TESTING 