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.
Assunto que nem todo mundo aceita, infelizmente.
ResponderExcluirGosto de pensar:
"Comente o porquê de ter feito algo e não o que algo faz."
http://en.wikipedia.org/wiki/Literate_programming
ResponderExcluir@wbotelhos, é por aí mesmo.
ResponderExcluir@Anônimo, nem tanto. O conceito é parecido, mas a implementação, completamente diferente.
claro, pois a sua proposta é completamente equivocada. os comentários devem ser usados sempre que necessários. exemplos em orientação a objetos de onde devem ser usados são para descrever as razões e princípios de funcionamento de uma classe (rationale) e para documentar métodos públicos. em outros paradigmas também devem ser utilizados para explicar algoritmos mais complexos, e não venha dizer que todo algoritmo deve ser simples o suficiente para ser entendido lendo o código. se vc pensa assim é pq nunca viu a implementação de um algoritmo realmente complexo - só para citar algumas áreas onde vc pode encontrar esses algoritmos: tratamento de grafos, otimização combinatória, aprendizado de máquina, visão computacional, computação gráfica, implementação de b-tress, parsers, etc. saiu do be-a-bá do controle de estoque de padaria os comentários tem uma enorme utilidade.
ResponderExcluir@Anonimo, concordo com vc sobre documentar algoritmos complexos. Eu mesmo tenho alguns códigos assim.
ResponderExcluirConcordo em parte sobre as classes. Descordo totalmente sobre os métodos públicos.
Gostei da sua colaboração. É bom trocar ideias.
Realmente escrever código limpo é uma necessidade cada vez maior para termos programas que possam ser mantidos mais facilmente.
ResponderExcluirMas comentários também são necessários para fins de documentação, conforme já citaram anteriormente.
Temos que saber dosar os dois na medida certa para termos codificação de qualidade