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. 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.
Comentários redundantes
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:
|
1 2 3 4 5 |
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!
Códigos comentados
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”.
|
1 2 3 4 5 6 7 |
// 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 no ato da alteração do código. 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.
Comentários obsoletos
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:
|
1 2 3 4 5 6 7 8 9 |
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? 🙂
Informação dos comentários
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:
|
1 2 3 4 5 6 7 8 |
// 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 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.
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.
|
1 2 3 |
// 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 consistente 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!
Muito bom André (: “Vou deixar as linhas aqui. Se der algum problema, é só descomentá-las”.) kkkkk
esse ai sou eu kkkk olhando como você falou quando se passa muito tempo isso realmente pode se torna problema , Parabéns pelo artigo (^_^).
Olá, André!
Obrigado novamente pelo comentário!
Isso mesmo, é bom nos atentarmos com o excesso de linhas comentadas no código-fonte. Além de prejudicar a legibilidade, também pode confundir outros desenvolvedores.
Abraço!
Parabéns pelo artigo André. De fato “Clean Code” ainda é um assunto muito incomum no mercado não somente de Delphi, mas todo ele. Li “O Codificador Limpo” também do ‘Tio Bob’ e recomendo que as empresas de TI incluam este livro nos PDIs de seus colaboradores. É praticamente um código de ética que nós, desenvolvedores PRECISAMOS ter e praticar assim como médicos e engenheiros possuem e praticam os seus. Clean Code é uma parte crucial no Desenvolvimento Sustentável de Software que prega softwares de qualidade com baixo custo de produção e manutenção. Abraços.
Fala, Marcos!
Em primeiro lugar, agradeço fortemente pela visita e por deixar um comentário muito importante sobre Clean Code. Concordo plenamente sobre o fato de disseminar as práticas de Clean Code dentro da empresa, talvez, como você disse, indicando a leitura do livro do ‘Tio Bob’ como algo mandatório. Gostei do termo “código de ética do desenvolvedor” que você empregou. É exatamente isso!
Nos últimos dois anos, tenho ajudado alguns desenvolvedores por e-mail, pela página do Facebook e através dos comentários do blog. Enquanto interpretava os códigos, notei que realmente há uma carência na qualidade técnica do código-fonte que é produzido pelos desenvolvedores em vários aspectos. Por conta disso, além da orientação, também venho recomendando práticas do Clean Code para que estes desenvolvedores, aos poucos, adquiram o hábito de escrever um código limpo, legível e expressivo.
Marcos, obrigado novamente! Grande abraço!