Comentários

Os comentários em códigos é um assunto muito debatido entre programadores e desenvolvedores em geral. Muitos preferem escrever várias linhas de comentários sobre o código e a cada linha é inserida um comentário sobre o que faz o código. Outros preferem não comentar o código ou evitam inserir muitos comentários. Mas qual a maneira correta de comentário? Na verdade não existe uma maneira correta ou uma receita de bolo. Existem apenas algumas boas práticas para criar comentários mais simples, bem elaborados e não poluir muito o código com este tipo de prática, veja abaixo algumas boas práticas, dicas e exemplos para escrever os comentários.

1 - Comentários redundantes

Existem alguns comandos das linguagens que são meramente óbvios, dispensando qualquer tipo de comentário. Veja o exemplo abaixo de comentários que são desnecessários, principalmente quando os desenvolvedores do grupo já possuem capacitação suficiente para compreender estes comandos com muita 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, e que expliquem o que o código não consegue explicar por si só.

2 - Códigos comentados

Códigos comentados também podem tornar-se um problema e poluir muito o algorítimo como um todo. Existem aquelas linhas que o desenvolvedor comenta temporariamente para fazer um teste pontual, e 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 sugestão é que esse tipo de comentário seja removido no ato da alteração do código. Se for preciso resgatá-lo, utilize o histórico do controle de versão que o Scripter disponibiliza 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.

Uma outra dica útil que pode ser relevante para esse caso, é inserir esse código e os comentários sobre ele após o End do script, assim ele não atrapalhará quem está prestando manutenção neste algoritmo ou implementando novas funcionalidades.

3 - Comentários obsoletos

Associado ao problema acima, há também 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. E este foi o resultado:

procedure GerarPlanilhaComissao(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.

4 - Informação dos comentários

Outro problema associado a comentários é o tipo de informação que é escrito. Uma grande parte de dos desenvolvedores 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 mencionado anteriormente, atualmente existem 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:

É fato que, dessa forma, quanto mais a aplicação evoluir, maior será a quantidade desse tipo de comentário, chegando ao ponto de prejudicar a leitura do código, e o pior é quando um desenvolvedor esquecer de não colocar esse comentário o mesmo além de atrapalhar a leitura do script ainda irá estar defasado.

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, e também preencher o campo de documentação no VsSCripter que está localizado no menu Project > Documentação, veja abaixo:

5 - Comentários mal escritos

Outro problema são os comentários mal escritos, talvez o pior deles. 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.

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