Page Comparison

...

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 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.

...

// 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!