Escreva comentários no código com moderação!

DAVID CANDIDO DA SILVA

DAVID CANDIDO DA SILVA Publicado 16/11/2017 


Quando precisamos anotar um detalhe no código, um lembrete ou uma explicação de uso de um método, os comentários caem bem. Podemos escrevê-los em qualquer parte do código para ajudar outros desenvolvedores na interpretação das regras. Contudo, por outro lado, comentários também podem atrapalhar, poluir ou confundir o código quando não empregados com prudência. Confira!

 

Já escrevi muitos comentários no código desde que me entendo por programador. Embora eles tenham me ajudado bastante, alguns comentários me desorientavam em função dos motivos que apresentarei abaixo. Ao ler o livro Clean Code, que faz uma breve menção dos problemas relacionados a comentários, identifiquei alguns pontos que me motivaram a elaborar esse artigo.

 

Um dos maiores problemas que encontro em comentários é a redundância. Existem alguns comandos das linguagens que são meramente óbvios, dispensando qualquer tipo de comentário, ao menos que sejam para fins acadêmicos ou didáticos. Por exemplo, os comentários no código abaixo são desnecessários, principalmente quando os desenvolvedores de uma empresa já possuem capacitação suficiente para compreender estes comandos com facilidade:

Query.Close; // fecha a Query
Query.SQL.Add('Select * from CLIENTES'); // preenche a propriedade SQL
Query.SQL.Add('where Codigo = :Codigo'); // adiciona a condição
Query.ParamByName('Codigo').AsInteger := nCodigo; // preenche o parâmetro
Query.Open; // abre a Query

Se realmente for preciso escrever comentários sobre determinados comandos, então que sejam relevantes e convenientes. Como diz Uncle Bob, comentários devem explicar o que o código não consegue explicar por si mesmo. Frase marcante!

 

O segundo problema são os próprios códigos comentados. Sabe aquelas linhas que o desenvolvedor comenta temporariamente para fazer um teste pontual? Então, após testar o código, muitos esquecem de remover essas linhas comentadas ou, no pior dos casos, pensam: “Vou deixar as linhas aqui. Se der algum problema, é só descomentá-las”.

// loop substituído pela atribuição da propriedade 'Text'
// for i := 0 to StringList.Count - 1 do
// begin
//   ComboBox1.Items.Add(StringList[i]);
// end;
  ComboBox1.Items.Text := StringList.Text;

A questão é que o tempo passa. Um, dois, três anos depois, esse código ainda estará lá, talvez fazendo referência a algo que não é utilizado há muito tempo. Aos poucos, outros desenvolvedores deixarão de se importar com este código comentado, sempre com o receio de removê-lo por pensar que, eventualmente, ele ainda será necessário.
A minha sugestão é que esse tipo de comentário seja removido o mais breve possível. Se for preciso resgatá-lo, utilize o histórico do controle de versão ou, na ausência de uma ferramenta dessa natureza, faça um backup do arquivo antes de remover o código, mas, seja qual for a ocasião, não deixe de removê-lo.

 

Associado ao problema acima, nos deparamos também com os comentários obsoletos ou defasados. Estes comentários originalmente são escritos para explicar o propósito de um método, descrever os parâmetros obrigatórios de uma função ou detalhar a utilização de variáveis. Porém, na maioria das vezes, o código passa por várias alterações e estes comentários deixam de ser atualizados, resultando em informações incorretas ou em uma explicação inválida.
Por exemplo, considere um método responsável por gerar uma planilha de comissão de um vendedor. Este método inicialmente recebia o código do vendedor como parâmetro, no entanto, por questões de segurança, o código do vendedor passou a ser obtido do usuário atual conectado ao sistema. Além dessa mudança, também foi solicitada a inclusão de um novo parâmetro referente ao nome do arquivo que será gerado. Diante de todas essas alterações, os desenvolvedores esqueceram (ou nem se mobilizaram) de atualizar os comentários já existentes. Este foi o resultado:

procedure GerarPlanilhaComissao(const psFormatoArquivo: string);
begin
  // Método responsável por exportar as comissões
  // do código do vendedor informado no parâmetro.
  // O valor do parâmetro pode ser obtido através da função ObtemVendedorBD();
    CriarDocumento(psFormatoArquivo);
  ExportarDadosComissao;
end;

Quando outro desenvolvedor ler este comentário, pensará: “De qual parâmetro sobre o código do vendedor ele está falando?!”. E mais, o comentário ainda faz alusão a um método que obtém o código do vendedor por meio de uma consulta no banco de dados, sendo que, na verdade, este código passou a ser obtido internamente. Que informação sem-vergonha, hein? 

 

Outro problema associado a comentários é o tipo de informação que escrevemos. Uma grande parte de empresas de desenvolvimento tem a cultura de adicionar informações de atualização (como o autor do código, data, número da ordem de serviço e/ou o nome do documento que contém a regra de negócio codificada), mas, como disse anteriormente, atualmente dispomos de várias ferramentas para essa finalidade, justamente para evitar que esse tipo de informação degrade as unidades de código, tornando-as maçantes para leitura.
Imagine que uma parte de um método tenha recebido alterações distintas nos últimos cinco meses e que, para cada alteração, foi solicitada a inserção das informações de alteração. Os comentários, no mínimo, seriam adicionados conforme abaixo:

// 08/10/2014 / Ordem: 154 / Autor: Leonardo / Doc: 681
// 14/12/2014 / Ordem: 275 / Autor: Donatello / Doc: 712
// 20/01/2015 / Ordem: 316 / Autor: Raphael / Doc: 844
// 02/03/2015 / Ordem: 490 / Autor: Michelangelo / Doc: 1150
sDataHoje := FormatDateTime('dd-mm-yyyy', Date);
sNomeArquivoLog := ExtractFilePath(Application.ExeName) + 'Arquivo - ' + sDataHoje + '.log';
GerarPlanilhaComissao(sNomeArquivoLog);
...

É fato que, dessa forma, quanto mais a aplicação evoluir, maior será a quantidade desse tipo de comentário, chegando ao ponto de prejudicar consideravelmente a leitura do código. A recomendação é utilizar ferramentas exclusivas para registrar esses históricos de alterações para que o código-fonte não receba essas informações.

 

Pior mesmo são os comentários mal escritos, talvez o pior dos problemas. A falta de coesão, erros de pontuação, imprecisão na gramática e até mesmo a escolha de palavras inapropriadas podem afetar a interpretação do comentário. Na realidade, é possível que o desenvolvedor gaste mais tempo tentando entender o comentário do que propriamente lendo o código.

// esse função recebe outro variável da classe complementar
// para consultar a inf. necessária para preencher uma propriedade do objeto;
// pf, não mexer na parte de processamento pq dá erro

A regra é simples: caso for necessário adicionar um comentário, escreva-o de forma consciente e não esqueça de revisá-lo para certificar-se de que o objetivo foi transmitido.

 

Amigos desenvolvedores, boa sorte nas suas próximas codificações e não se esqueçam de fazer uso dos comentários com moderação!
Um grande abraço!

 

Voltar ao topo