O que não comentar

Ler comentários requer tempo, atenção e ocupa certo espaço da tela. Por isso é importante evitar comentários inúteis que apenas atrapalham.

Deve-se evitar comentários que não acrescentam nenhuma informação ou não ajudam a entender o código.

Não se comenta fatos que podem ser identificados facilmente apenas lendo o próprio código. Neste caso define-se “fácil” quando o tempo necessário para entender o código for o mesmo ou menor que o tempo necessário para ler o comentário.

Exemplo:

//Definicao da classe Conta

Class Conta

Method New() Constructor // Construtor da classe

Method SetSaldo(nValor)  // Altera o saldo da conta

Method GetSaldo()       // Retorna o saldo da conta

EndClass

Os comentários acima não acrescentam nenhuma informação que não possa ser extraída facilmente lendo o próprio código.

Porém, algumas vezes o código não é tão simples. Nesses casos mesmo um comentário que não acrescente nenhuma informação nova pode ser útil, para facilitar o entendimento do código que não é tão óbvio.

Exemplo:

// Posicao da observação no array

Local nPosOBS  := AScan(aHeader, {|x| AllTrim(x[2]) == "ADF_OBS"})

Os comentários também não devem ser utilizados para maquiar um código ruim ou gambiarras. Ao invés disso, arrume o código.