...
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:
Code Block | ||
---|---|---|
| ||
// 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.
Code Block |
---|
...
| ||
// 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!