Comentários em código fonte, por favor, não!

Publicado: 12 de setembro de 2013 em Uncategorized
Tags:

Antes de escrever este texto eu fui procurar algumas opiniões já publicadas sobre isso. Não consegui ir muito longe porque me deparei com um verdadeiro show de horrores e fiquei paralisado. Encontrei uma verdadeira tese ensinando a comentar código fonte!

Quando comecei a ler eu achei que o cara estava de brincadeira, que era uma pegadinha e que no final ele esclareceria tudo. Mas não!No finalzinho ele até diz que os comentários no código fonte devem explicar o porquê e não o como, mas daí ele já estava contrariando todas as outras dezenas de páginas do artigo onde uma tragicomédia é apresentada em muitos atos.

Bem, me inspirando no artigo dele (acho que ele não se importa) desmistifico a seguir algumas “necessidades” de se comentar código fonte. Não vou argumentar cada equívoco deste site inspirador; apenas alguns.

(…) you should strive towards clean and readable comments to further explain confusing areas in your code.
Correção:
Você deve perseguir um código fonte limpo e legível de modo que seu código não fique confuso e não exija mais explicações.

Continuando…

Sometimes as developers we forget that we’re writing comments for humans to read. All of the programming languages we understand are built for machines.

Mas em que linguagem ele andou programando? As linguagens que eu usei até hoje, bem como as que ele usa nos exemplos, são de alto nível e estão direcionadas para o entendimento humano e não das máquinas. Esta sentença pode ser facilmente corrigida jogando metade fora e substituindo uma palavra na outra metade que sobrou:

Algumas vezes como desenvolvedores nós esquecemos que estamos escrevendo código fonte para humanos lerem.

Existem formas mais eficientes de falar para um computador do que usando Java, C#, Visual Basic, Delphi, PHP… Usar estas linguagens não se trata de falar com máquinas, se trata de falar com pessoas. Quando meu aplicativo está sendo executado pelo computador, nenhuma linha que eu tenha escrito será lida. O computador vai ler coisa mais interessante pra ele do que isso. A forma como eu escrevi as linhas são para meus colegas e eu lermos.

I’ve added some meta information with my name and email address for contact. When developers are writing open source code this is generally good practice so others may contact you for support. This is also a solid method when working in larger development teams.

Confesso que eu continuo procurando no site indícios de que isso seja uma piada no estilo desciclopédia!

Em que projeto open source ou times grandes ele andou trabalhando? Identificar o autor através de comentários no código fonte era o único jeito que eles tinham de saber quem fez o que? Eu prefiro contar com um gerenciamento de configuração de software para isso, usando ferramentas como Subversion, Team Foundation Server, IBM RTC, Git… Além do mais, é improvável que em um time apenas uma pessoa seja responsável por uma classe inteira, para todo o sempre. Quando usei NetBeans para programar em Java me incomodou bastante o template padrão escrever meu nome em cada novo arquivo que eu criava. Isso era completamente desnecessário porque o Subversion já me dizia quem tinha escrito ou alterado cada linha do projeto, e se alguém alterasse todo o corpo da classe e até o nome dela e não atualizasse o comentário, além de desnecessário o comentário passaria ser mentiroso.

Em seguida o artigo apresenta um exemplo do tipo de comentário que seria bem vindo:

function getTheMail() {
   // code here will build e-mail
   /*run code if our custom sendMyMail() function call returns true
     find sendMyMail() in /libs/mailer.class.php
     we check if the user fills in all fields and message is sent! */
   if(sendMyMail()) { return true; // keep true and display onscreen success
   }
}

E eu apresento soluções para não precisar comentar este código:

  • code here will build e-mail. Se o que a função faz é “build e-mail”, então este deveria ser o nome dela, o que dispensaria comentários.
  • run code if our custom sendMyMail() function call returns true. Bem, ele só adicionou texto inútil ao texto funcional que é o próprio código fonte, já bastante claro “if sendMyMail()”.
  • find sendMyMail() in /libs/mailer.class.php. É triste não ter uma IDE que nos indique onde encontrar um código fonte. Muito triste! Até porque o código muda de lugar e o comentário passa a ser inútil ou mentiroso. De modo que mesmo que você não possa usar uma IDE melhor, ainda é melhor não comentar.
  • we check if the user fills in all fields and message is sent. Indício de código que pode ser melhorado: a função faz isso e faz aquilo. Se eu preciso de um “e” para descrever o que uma função faz, então eu deveria ter duas funções, cada uma cumprindo uma das tarefas, e cada uma das funções poderia ter um nome bem descritivo que dispensasse comentários.
  • keep true and display onscreen success. O que uma exibição de uma mensagem em tela tem a ver com uma função que envia e-mail? Um melhor design do aplicativo evitaria essa confusão, que evitaria a necessidade do comentário.

Mau conselho:

As a general rule of thumb, take some time to pause and reflect before writing [comments]. Ask yourself what is most confusing about the program and how can you best explain it in “dummy” language?

Um conselho melhor:

Como regra geral, reflita um pouco antes de escrever o código fonte. Pergunte-se o que está confuso no código e como você pode refatorá-lo para que ele fique auto-explicativo sem necessitar de explicação adicional?

Em seguida ele afirma:

Both your future self and your teammates will thank you for leaving comments ahead of time.

Ah, com certeza. Eu já consigo me imaginar agradecendo alguém por isso: “muito obrigado por ter feito esse péssimo código que exige comentários e não ter esquecido de escrever os comentários!”.

Mas por que afinal eu não devo adicionar comentários no código fonte?

Necessidade de comentários em código fonte não é um indício de que o código está ruim. É uma prova. Código de qualidade é claro, legível, auto-explicativo, dispensa comentários.

Código ruim diminui a qualidade do sistema, aumenta o custo de manutenção e dificulta sua evolução. Além do mais, quando modificamos o código fonte dificilmente atualizamos os comentários, o que torna os comentários inúteis ou mesmo perigosos.

Linguagens de programação de alto nível são pensadas para imitar a forma humana de se expressar. Podemos manter a mesma motivação e usá-las para escrever código para humanos lerem.

E como evitar comentários no código?

Resumo algumas técnicas muito simples que, enquanto diminuem a necessidade de comentários, melhoram a qualidade do código:

  • Todo artefato (variável, classe, método, arquivo) deve ter um nome muito significativo que revele sua função no sistema. Dificuldade para escolher nome pode ser um sinal de que a função do artefato não está bem desenhada.
  • Cada artefato deve ter apenas uma única função. Se foi necessário usar um “e” para descrever um método (“a função faz isso e aquilo”) ele deve ser refatorado.
  • Não usar IFs encadeados. Um IF dentro de outro é ruim. Um IF dentro de outro e dentro de outro (dois IFs encadeados) é inadmissível. Já vi código com tanto IF encadeado que havia comentários até pra tentar explicar a qual bloco pertencia o “end if”.
  • Variáveis devem ter o menor escopo possível e devem ser declaradas o mais próximo possível da linha onde serão utilizadas. Ok, em algumas linguagens isso pode ser um pouco difícil. Em Delphi, por exemplo, o menor escopo de uma variável é o método. Isso já é um escopo grande demais, então a próxima técnica deve ajudar.
  • Manter classes e métodos muito curtos. O quão curto? Se cada artefato estiver realmente cumprindo uma única função, ele já deve estar curto o bastante.

Existem princípios (SOLID), design patterns (DDD), práticas de engenharia (TDD, BDD) e boa literatura (Clean Code) que nos ajudam a escrever somente código funcional, código executável inclusive para justificar regras de negócio, os porquês, eliminando completamente a necessidade de comentários e mantendo baixa a complexidade do sistema. Nada disso é trivial de usar, mas minha última observação neste texto é bastante trivial e pode ser praticada ainda antes de estas ferramentas serem adotadas:

Procurar escrever código fonte claro o bastante, a ponto de dispensar a necessidade de comentários, melhora a qualidade do sistema.

Seria isso.

Anúncios
comentários
  1. phsbnu disse:

    Não concordo totalmente com o texto, no entanto opiniões radicais me fazem pensar. Com as devidas ponderações eu posso afirmar vejo valor nele. Assim como hoje eu vejo valor nas broncas, por vezes exageradas, que meus pais me davam quando fazia algo errado 🙂

    A lição que levo, que aliás não é nenhuma novidade é: Lembre-se que o código tem que ser legível. Não utilize comentários numa tentativa de tornar um código ruim, melhor.

  2. Maja da Rosa disse:

    Vou lembrar dessa sua lição para sempre.
    Muito bom ter ela por escrito para poder passar para frente.
    E junto com este aprendizado, adicionarei uma parte do comentário acima: “Não utilize comentários numa tentativa de tornar um código ruim, melhor.”

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s