Qualquer coisa que esteja no programa fonte que não seja comando da linguagem, é ruído. E comentário é um deles.
Se seu programa precisa de comentários, ele não é claro para uma pessoa entender.
Escreva programas mais simples, mais fáceis de entender. Assim, ele são menos propensos a erro e não há necessidade de comentários. Aliás, os comentários são como mato: brotam onde não deveriam existir. Se um programa é bem escrito, de maneira clara, quase nunca vai precisar de comentários.
Desculpe, mas eu nunca vi um programador o tempo todo preocupado em deixar os comentários atualizados. Quando o programa é criado, está tudo bonitinho, mas com o passar dos meses (e dos anos!) e com o ritmo de trabalho, duvido que os comentários retratem o que o código fonte realmente faz. Infelizmente os comentários não acompanham o programa.
Note que não sou contra os comentários. Sou a favor deles, nos lugares que realmente são necessários. Mas esses lugares são raríssimos!
Ao invés de adotar um estilo claro de comentários, adote um estilo de codificação que permita às pessoas entenderem melhor seu código. Afinal, qualquer um escreve código que os computadores entendem. Os bons programadores escrevem código que outras pessoas entendem.
A ideia é simplificar a vida de quem vai dar manutenção em seus programas. Digo sempre que você pode dar o azar de ter que mexer num programa que você mesmo escreveu há 6 meses atrás. Será que você vai lembrar o que quer dizer aquele
(if $codigo == 8)? E o return -2, o que significa mesmo?Vamos a um exemplo (em PHP) de uma situação que você, programador consciente, pode aproveitar para tornar seu programa mais limpo e expressivo.
Evite os números mágicos e os códigos.
Ao invés de escrever isso:
if ($usuario['perfil'] == 1) { // vendedor
return -2; // nao autorizado
}
if ($usuario['perfil'] == 2) { // financeiro
return 1; // ok
}
Use métodos e constantes no lugar dos números mágicos:
if (ehPerfilVendedor($usuario['perfil'])) {
return PERFIL_NAO_AUTORIZADO;
}
if (ehPerfilFinanceiro($usuario['perfil'])) {
return PERFIL_OK;
}
Escreva programas que sejam claros para as pessoas. Deixe seu programa falar por si só.
Como esse assunto é longo, em breve teremos mais um post sobre como escrever programas mais fáceis de entender.
