Comentar o código

Como todos (os que alguma vez programaram) sabemos que uma de coisas fundamentais de um programador é ter o código bem organizado e comentado. É mesmo essencial! Todas as funções e procedimentos têm que ter uma breve descrição do que fazem e mesmo dentro delas convem dar alguns comentários ao que está a ser feito. Isto facilita a leitura do código pelas outras pessoas e pelo próprio criador, quando já não lembrar nada do que fez (acontece tantas vezes, somos amnesicos!)...
Até vos posso dizer que já fiz algumas aplicações que tinham mais comentários do que o próprio código...

Isto foi a introdução ao que vou apresentar a seguir. Num site onde fui parar (tive que alterar esta frase visto que o site foi me indicado por um amigo para me despachar enquanto estava estudar para um exame e hoje, depois de exame, viu que não o referenciei, e começou a resmungar!!!! aqui vem) que o meu amigo Ricardo indicou (espero que estejas te sentir melhor!!!:)) encontrei muitas piadas sobre os dummies e esta foi uma que me chamou atenção:

When a computer professor asked his students to comment all their programs, he
got remarks like:
"This program is very nice."
"This program is very
difficult."
"This program is very interesting."

Inspirada, vou dar vos alguns exemplos de comentários bem sucedidos e abrangentes que se podem fazer no código:

• Esta função não é só gira, funciona!
• Esta função é fixe
• Este procedimento funciona
• Este procedimento não funciona, mas é giro
• Este procedimento não sei o que faz, mas fui eu que fiz
• As funções que seguem funcionam!
• Esta função é dificil, mas não é gira
• Esta função devia fazer ... mas não faz, mas é gira
• Esta função funciona mas não está a ser usada em lado nenhum. Por isso ainda não sei o que faz...
• Se esta função der erro, evitem usa-la novamente...
• Esta função é fixe, fiz sozinha
• Esta dll funciona... se não conseguir po-la a funcionar, não faz mal, ela funciona na mesma!

:) Agora vou voltar ao trabalho e aos comentários que faço no código:)

Abraço

P.S. Aguardo as novas ideias inspiradas nos comentários nos comentários a este post:D