Comentários no fonte . Bom ou Ruim?

[Thiago Adams]

Para não misturar com a outra thread criei este novo tópico.

Eu evito colocar comentários no fonte.
A maior parte dos comentários demostram que o código foi mal escrito.

ex:

1) Comentario obvio:

1a) m_i++; // incrementa
1b) class X // declacao da classe X
1c) X::X // constructor
etc
etc
etc

2) Comentário de função mal nomeada.
Algu'em tenta explicar o que o nome da fun'cao deveria dizer.

do(x); // faz o update com x

2b) coment'ario de membro mal nomeado

m_i; // contador


3) "Função inline"

É a documentaçào de um bloco que deveria ser uma função. ('e bem
comum)

void f()
{
int a = 1;
int b = 2;

//faz o swap
int temp = a;
a = b;
b = temp;
}

4) Coment'ario de pre condicoes
void f(char *p)
{
//p nao pode ser null
}
Para isso se usa o assert

5) coment'ario inutil

SetName // Esta funcao seta o nome
GetName // esta funcao pega o nome.

etc..


Se a documentacao tem a finalidade de dar uma ideia do que foi feito e
explicacao dos algoritmos eu sou a favor de colocar num wiki.

Existe um caso especial de documentacao no fonte que tem que ser feita
para tudo incluindo o obvio que 'e quando se distribui uma lib e seu
manual. Neste caso pode ser util usar um gerador e poluir o fonte todo
de comentarios para ter o beneficio de gerar a documentacao
automaticamente. Nos outros casos vale os comentarios que coloquei
acima.

[Thiago Adams]

6) Outra coisa comum sao comentarios desatualizados.

[Blabos de Blebe]

Eu prefiro comentários no fonte, pois eu (normalmente) tenho acesso ao
fonte e nem sempre ao manual, e se os comentários forem bem feitos, dá
pra gerar o manual do código. Desde que não sejam comentários do tipo
que você listou.

Não acho que comentários bem feitos poluam o código.

Detesto manuais automáticos que vem de comentários mal feitos. O
resultado é um manual ainda pior.

Bibliotecas deveriam ter seu manual, mas nem sempre tem. É a vida.

Comentários existem por um motivo. Auxiliar.

Se eu tiver que programar sem comentários, vou programar em Perl que é
mais legível que C++. E nesse caso me refiro a códigos bem escritos em
ambas, ok!?

Código obscuro é sempre obscuro, seja em PHP, C++ ou Assembly. Tendo
comentário ou não.





2009/6/25 Thiago Adams <thiago...@gmail.com>:

[Caloni]

É bem conhecido de quem já viu muito código de terceiro que a maioria
de comentários encaixa-se nessa crítica do Thiago. E, pior ainda,
quando alguma existe alguma coisa não-trivial, anti-intuitiva ou
simplesmente vital para o funcionamento do software e que não pode ser
alterado de jeito nenhum, daí sim não existe comentário nenhum. O que
é fácil de explicar: o começo de um projeto feito às pressas nunca é
comentado corretamente. Isso faz com que o "legado" do core acompanhe
o projeto por toda a vida, sem ter sido comentado/entendido
corretamene pelos seus "herdeiros".

[]s

> 2009/6/25 Thiago Adams <thiago.ad...@gmail.com>:

[DQ]

Thiago,

Embora a maioria dos comentários que se encontre se encaixem no que
você diz, existem sim comentários bons. E quando você tem que dar
manutenção em um software e encontra um destes casos é como uma
revelação divina.

Como <a href=http://dqsoft.blogspot.com/2007/10/desenvolvendo-
softwares-agradveis-de.html>disse uma vez no meu blog</a>, considero
que "Bons comentários são os que destacam as coisas não óbvias ou
resumem o que um trecho mais complicado faz. Comentários ruins são os
mentirosos (lembranças de cut-and-paste apressados ou não atualizados
após mudanças) e os inúteis (que só ocupam espaço e reduzem a
atenção).".

A documentação fora do fonte tem maiores probabilidades de se perder
ou ficar desatualizada. Como você mencionou, a documentação pode ser
extraída dos comentários (eu uso com frequência o Doxygen).

Comentar direito não é fácil, mas eu continuo tentando.

[Thiago Adams]

A política que adoto é a seguinte:
Toda vez que penso em um comentário verifico o motivo pelo qual o
fonte por si só não está dizendo aquilo. Na maioria das vezes, criar
uma função, renomear etc resolvem o problema.
Algo interessante de se fazer é pedir para um colega olhar rapidamente
sua função sem nenhum comentário no fonte, e perguntar à ele o que
ele acha que a função faz. A mesma coisa para uma classe e seus dados
membros.
É melhor que ele entenda o que a função faz do que ter uma função que
parece fazer uma coisa e fazer outra. E um comentário explicando esta
outra coisa coisa.
Até porque, durante a chamada da função ninguém vai ficar comentando o
que ela faz. Aliás, existe este caso também, tem gente que explica o
que a função faz em cada chamada.

Basicamente as pessoas fazem um codigo complicado e depois tentam
explicar a complicação que fizeram.


A documentação externa de uma idéia, não precisa ser tão detalhada .
No máximo nome de classes. E assim sendo, a chance de ficar
desatualizada é menor. E mesmo que esteja desatualizada, "versao 1"
não quer dizer que não possa ser usada para entender a versão 2.


Só para lembrar e repetir, no caso de uma empresa fazer uma lib para
terceiros, cada coisa tem que ser documentada, e neste caso (que não é
o meu) um gerador automatico é uma boa solucao.

No outro post falávamos de padrões de projeto. Mas também existem
padrões de codificação que substituem comentários.
Ex: Colocar um "I" na frente do nome da classe substitui o comentário,
"Isto é uma interface".

[A.F.]

Well,

Há casos e casos, concordo em parte com tudo o que foi discutido aqui..

<LOL>

Um ex-colega de firmware escrevia uma Bíblia nos seus comentários,
normalmente eles eram muito maiores que suas instruções e algumas
vezes ele escrevia toda uma articulação de defesa de sua instrução que
era equivocada.

</LOL>

Principalmente quando se mistura assembly ou construções não
triviais, confesso que eu faço comentários que podem pareceber óbvios
mas isto ajuda quem vai dar manutenção, principalmente novatos e
programadores sem vocação mística. Como normalmente meus códigos
acabam passando por dúzias de outros analistas e engenheiros e às
vezes se tratam de drivers com detalhes bizarros e principalmente com
instruções vinculadas a ghost protocols praticamente imutáveis, por
mais óbvio que pareça para uns, para muitos certos comentários são
fundamentais. Porém, há instruções que simplesmente porque funciona
muitos nem se preocupa em entender como funciona e o comentário lúdico
se torna inútil da mesma forma.

Mas costumo deixar comentários para alimentar o Doxygen, algumas
instruções que foram substituídas, comentários para construções de
difícil compreensão e principalmente instruções que acabei percebendo
que por necessidades de otimização ou para resolução de efeitos
colaterais tiveram que ficar do jeito que estão.

Agora, confesso que muitas vezes vou simplesmente codificando e os
comentários ficam para depois, sendo-se que para alguns códigos este
depois nunca chegou...

Ps: Aos que aqui estão e já pegaram meus códigos com parser de
protocolos sem comentários, so sorry! Não foi maldade (tsc)...

[ ]s

Alberto

/*
#
# The best way to predict the future is to invent it , Alan Key
#
// 0x42 0x69 0x74 0x20 0x46 0x61 0x6e */



2009/6/26 DQ <d.qu...@yahoo.com>:

[Rodrigo Kumpera]

Existem muitos motivos válidos para deixar comentários no código.
A maioria é resultado da manutenção do software. Como modificações
estranhas para manter compatibilidade, ou soluções meia boca adotadas
por conta de restrições de tempo, ou tantas outras.

Fora que as vezes realmente não tem como esperar que um pedaço de código
seja auto explicativo. Então você usa comentários p/ explicá-lo ou indicar links
a respeito. Principalmente pq normalmente é muito mais importante entender
qual o algorítmo usado do que o código em sí.

2009/6/26 Thiago Adams <thiago...@gmail.com>

[A.F.]

2009/6/25 Blabos de Blebe <bla...@gmail.com>:

>
> Eu prefiro comentários no fonte, pois eu (normalmente) tenho acesso ao
> fonte e nem sempre ao manual, e se os comentários forem bem feitos, dá
> pra gerar o manual do código. Desde que não sejam comentários do tipo
> que você listou.
>
> Não acho que comentários bem feitos poluam o código.
>
> Detesto manuais automáticos que vem de comentários mal feitos. O
> resultado é um manual ainda pior.
>
> Bibliotecas deveriam ter seu manual, mas nem sempre tem. É a vida.
>
> Comentários existem por um motivo. Auxiliar.
>
> Se eu tiver que programar sem comentários, vou programar em Perl que é
> mais legível que C++. E nesse caso me refiro a códigos bem escritos em
> ambas, ok!?
>
> Código obscuro é sempre obscuro, seja em PHP, C++ ou Assembly. Tendo
> comentário ou não.
>

Também concordo que código obscuro é sempre sobrio, independente da
linguagem de programação, a questão é se ele assim ficou por estilo de
escrita da mente codificadora ou se ele assim parece ser não por
inteção de causar confusão mas por que o tipo de construção necessita
ser assim. Por exemplo, para alguns código com assembly é sempre
confuso e sinistro, so sorry!

[ ]s

A.F.

/*
#
# The best way to predict the future is to invent it , Alan Key
#
// 0x42 0x69 0x74 0x20 0x46 0x61 0x6e */


>
>
>
>

[A.F.]

2009/6/26 Rodrigo Kumpera <kum...@gmail.com>:

> Existem muitos motivos válidos para deixar comentários no código.
> A maioria é resultado da manutenção do software. Como modificações
> estranhas para manter compatibilidade, ou soluções meia boca adotadas
> por conta de restrições de tempo, ou tantas outras.
>
> Fora que as vezes realmente não tem como esperar que um pedaço de código
> seja auto explicativo. Então você usa comentários p/ explicá-lo ou indicar
> links
> a respeito. Principalmente pq normalmente é muito mais importante entender
> qual o algorítmo usado do que o código em sí.

Yep! Links também são válidos, eu também utilizo deste artifício,
penso ser um infelicidade quanto eles quebram. Para tentar evitar
isto, já me solicitaram para deixar cópias destes conteúdos em
intranet porém eu nunca o fiz por achar que poderia ser pior.

[Thiago Adams]

On 26 jun, 09:55, Rodrigo Kumpera <kump...@gmail.com> wrote:
> Existem muitos motivos válidos para deixar comentários no código.
> A maioria é resultado da manutenção do software. Como modificações
> estranhas para manter compatibilidade, ou soluções meia boca adotadas
> por conta de restrições de tempo, ou tantas outras.

Eu concordo..
Nestes casos as vezes eu coloco um comentário que o número do case/
ticket/defect que gerou aquela moficação, ou que tem relação com
aquela parte do fonte.
Ou no caso em que o fonte não é auto explicavo mas não pode ser
alterado pois não vale a pena.

[A.F.]

2009/6/26 Thiago Adams <thiago...@gmail.com>:

<OFF>

Boa, neste contexto acho engraçado os conflitosas gerados por tickets
que acabam solicitando a alteração de um código que já sofreu
manipulação por outros tickets. Lei de Murphy

[ ]s

[Márcio Gil]

Também uso poucos comentários no meu código. Porém com o tempo fui
confluindo para um padrão de comentários parecido com títulos e
sub-títulos em um texto técnico. Dessa forma posso olhar um código
complexo e entender a idéia geral só olhando os comentários, da
mesma forma que você pode ler o sumário de um artigo e ter uma visão
macro do que trata o artigo.

Quando é uma função pequena só a descrição da função já basta. Porém
comentários elucidativos, como explicar uma fórmula, comentar de
onde foi tirado um algoritmo ou mencionar referências, são
essenciais.

> -----Mensagem original-----
> De: Thiago Adams

[Guilherme Rezende]

Comentario no codigo é algo critico,
se for fazer, faça bem feito, pois existem comentarios que pode levar um programador posterior, a querer cometer suicidio.
exemplo:

#define C__BA    0x2FFD /* Verificar com [FULANO] Ramal:[XXXX] */
#define C_T  0x2FFE /* Verificar com [CICLANO] Ramal:[YYYY] */

código feito a seculos atrás... e eu ainda quis arriscar ligando nos ramais =X

2009/6/26 Márcio Gil <marci...@bol.com.br>

--
Guilherme BR {
     Linux ID: #437053
     www.guilhermerezende.com
}

[Ziviani]

/* Verificar com [FULANO] Ramal:[XXXX] */

Respeito o sofrimento que você deve ter passado, mas isso foi comédia demais. Parece que a pessoa fez de propósito, só pra sacanear.

mas botar o nome de uma pessoa com ramal e, ainda por cima, nem sequer colocar uma breve descrição é de matar.

2009/6/26 Guilherme Rezende <guilh...@gmail.com>

--
José Ricardo Ziviani

[Bruno Sanches]

Eu ja peguei:

try

{

///codigo

}

catch(SomeException &e)

{

    //we should handle those

    throw;

}

catch(AnotherException &e)

{

    //we should handle those too

    throw;

}

Detalhe que esse codigo foi copiado e colado por todos os metodos da classe...

Bruno Sanches
========================
http://bcsanches.wordpress.com

2009/6/26 Ziviani <jrzi...@gmail.com>

[Felipe Magno de Almeida]

2009/6/26 Guilherme Rezende <guilh...@gmail.com>:

> Comentario no codigo é algo critico,
> se for fazer, faça bem feito, pois existem comentarios que pode levar um
> programador posterior, a querer cometer suicidio.
> exemplo:
>
> #define C__BA    0x2FFD /* Verificar com [FULANO] Ramal:[XXXX] */
> #define C_T  0x2FFE /* Verificar com [CICLANO] Ramal:[YYYY] */
>
> código feito a seculos atrás... e eu ainda quis arriscar ligando nos ramais
> =X

Foi mto boa mesmo hahaahaha

[snip]

--
Felipe Magno de Almeida

[Thiago Adams]

Mais comentário reais:

//Atenção, este fonte não foi testado!

//TODO

//Adicione seu código aqui.

[gabriel]

#region Código Comentado - André 19/09/2008 Código Descomentado em
25/09/2008 por Vitor
// Tentativa de evitar o erro nos índices da tabela em
memória,
// trocando Bind por redirect, obrigando a uma nova
paginação do GridView.

...........

#region Código Comentado - Vitor 25/09/2008

//Response.Redirect(Request.Url.ToString(), true);

#endregion


sem mais.

[Bruno Sanches]

O codigo q trabalho hoje é lindo e cheio de:

int main()                                          /* FIX XYZ */
{                                                   /* FIX XYZ */
  string s("asdfg");                                /* FIX XYZ */
                                                    /* FIX XYZ */
                                                    /* FIX XYZ */
  list<char> list1(s.begin(), s.end());             /* FIX XYZ */
  list<char>::iterator i;                           /* FIX XYZ */
                                                    /* FIX XYZ */
  for (i = list1.begin(); i != list1.end(); ++i)    /* FIX XYZ */
    cout << *i;                                     /* FIX XYZ */
                                                    /* FIX XYZ */
                                                    /* FIX XYZ */
  reverse(list1.begin(), list1.end());              /* FIX XYZ */
                                                    /* FIX XYZ */
  for (i = list1.begin(); i != list1.end(); ++i)    /* FIX XYZ */
    cout << *i;                                     /* FIX XYZ */
                                                    /* FIX XYZ */
                                                    /* FIX XYZ */
  return 0;                                         /* FIX XYZ */
}                                                   /* FIX XYZ */

É adoravel editar codigo com esses comentarios uteis do lado...

Bruno Sanches
========================
http://bcsanches.wordpress.com

2009/6/26 gabriel <newbi...@gmail.com>

[Bruno Binelli]

Diretamente do Japão:

 

/*
 * ‘€ ì—š—ðŠÇ— ‹N“®—v‹
 */
/*
 * ‹@”\ŠT—v
 *   ‘€ ì—š—ðŠÇ— (...)‚Ì‹N“®—v‹ ‚ð s‚¤
 *
 */
/*
 *  ƒR [ƒŠƒ“ƒOƒV [ƒPƒ“ƒX
 *
 *    int CreateServer(CString& errStr) ;
 *
 *  ƒpƒ‰ƒ [ƒ^ à–¾
 *    errStr    (O) ƒGƒ‰ [“à—e
 *
 *    –ß‚è’l
 *       0 : ³ í
 *      -1 : ˆÙ í
 *
 * •â‘« à–¾
 *
 */
int CreateServer(CString& errStr)
{
:

 

Não é lindo?

2009/6/26 Bruno Sanches <bcsa...@gmail.com>

[Bruno Sanches]

Isso me lembra os samples de um certo console de  uma certa fabrica de televisoes do japao..

alem da documentacao oficial deles ser muitoa boa e explicativa, com funcoes e explicacoes do tipo:

int initvideo(int, int);

Initializes the video.

Nao estou forcando nao, era assim mesmo...

Bruno Sanches
========================
http://bcsanches.wordpress.com

2009/6/26 Bruno Binelli <brunob...@gmail.com>

[Bruno Binelli]

rsrs...

Por curiosidade, um dia procurei a tradução de um desses comentários e encontrei algo do tipo:

 

// create the server

createServer();

2009/6/26 Bruno Sanches <bcsa...@gmail.com>

[Marcio Gil]

Então meu método de comentar está incorreto?

Se você encontrasse este código: http://pastebin.ubuntu.com/204894/
O que você faria?

a) manteria como está (aprovando o sistema de comentários);
b) manteria como está (embora os comentários sejam desnecessários);
c) removeria todos os comentários do código;
d) apagaria tudo e faria outro código (sem comentários);

On Jun 26, 3:38 pm, Guilherme Rezende <guilherm...@gmail.com> wrote:
> Comentario no codigo é algo critico,
> se for fazer, faça bem feito, pois existem comentarios que pode levar um
> programador posterior, a querer cometer suicidio.
> exemplo:
>
> #define C__BA    0x2FFD /* Verificar com [FULANO] Ramal:[XXXX] */
> #define C_T  0x2FFE /* Verificar com [CICLANO] Ramal:[YYYY] */
>
> código feito a seculos atrás... e eu ainda quis arriscar ligando nos ramais
> =X
>

> 2009/6/26 Márcio Gil <marciom...@bol.com.br>

[Vanessa Leite]

Eu manteria como está.

:D

E aprovo o sistema de comentários.

Acho que comentários no código-fonte são tão bons, se não melhores que uma documentação.

Claro que há casos e casos.

Eu acredito que comentários em um código fonte podem ser escritos com a própria programação. Colocando nomes de variáveis, métodos e funções, claros, nos quais você entenda o que eles fazem, havendo apenas uma complementação com comentários. 

Existem fontes meus de maratona de tempos atrás (quando você tá numa maratona você não se preocupa em comentar código né?) que se eu pegar hoje, não sei oq cada coisa faz.. são variáveis com nomes de 'a' a 'z', independente de serem contadoras ou nao, além de funções com nomes fazTudo(), nada(), ou qualquerCoisa().

Entregar um fonte assim para alguém é até sacanagem.

=*

2009/6/27 Marcio Gil <marci...@bol.com.br>

--
Vanessa Leite
---
Ciência da Computação
Universidade Federal do Maranhão - UFMA
Connection - Empresa Junior de Computação - Diretora de Marketing e Relações Públicas
'DiOTT - Debug is On The Table'
(Maratona de Programação)
Alfred Hitchcock  - "Television has brought back murder into the home - where it belongs."

[Blabos de Blebe]

se o cara tiver sido eu, pediria demissão e iria pro interior plantar berinjela

2009/6/27 Blabos de Blebe <bla...@gmail.com>:
> e) demitiria o cara que fez isso ;)
>
> 2009/6/27 Vanessa Leite <vanessinhal...@gmail.com>:

[Blabos de Blebe]

e) demitiria o cara que fez isso ;)

2009/6/27 Vanessa Leite <vanessinhal...@gmail.com>:

[Eric Chiesse]

Manteria o sistema certamente.

Embora sejam em alguns casos até óbvios os comentários deu pra ter uma
noção geral do que foi feito em uns 20s. Digo isso em especial para o
interior das funções. Se precisar alterar alguma coisa eu acho fácil o
ponto certo e tb dá pra ter uma idéia macro do algoritmo.

Pra quem tem que pegar o código pela primeira vez é um grande adianto.

[Hélder Gomes]

O melhor comentário que eu já vi é o da bibiloteca de Objective-C Cocos2D para iPhone...

Eu fui contratado para aprender e programar essa bagaça (pq a empresa não achou nem quem quisesse aprender Oo)

Ai cheguei lá e vi uma função em um código fonte de outra pessoa (a única forma de aprender, a bibiloteca não tem "getting started"): AtlasSprite.

Ai resolvi ler a documentação, que descobri que é só aquele doxygen gerado com os comentários (ou seja, ler o fonte direto seria melhor... Mas como eu já tinha aberto a documentação mesmo...)

AtlasSprite: AtlasSprite is a class inherited from CocosNode.

Ai fui no CocosNode.

CocosNode: CocosNode is a parent class of all node type classes.

No fim tive que me virar para descobrir o que diabos o treco fazia...

Depois achei uma classe chamada "Lens3D" ai a documentação dela dizia na seção "detailed information": "Read file Lens3D" o texto era um link... Ai cliquei... Ai abriu a página que eu já estava (ou seja, onde está escrito para justamente ler ela mesma...)

Espetacular documentação feita com doxygen em cima de comentário porco... Muito útil saber que a classe SpriteManager é... uma classe...

2009/6/27 Eric Chiesse <echi...@gmail.com>

[Márcio Geovani Jasinski]

Olá,

Márcio, eu você tem um exemplo muito ilustrativo aqui: http://pastebin.ubuntu.com/204894/

Eu diria que seus comentários se fazem necessários pois você não quebrou o problema...

E isso acontece o tempo todo nos códigos que preciso alterar as vezes. Quando não tem nenhum comentário, eu sofro para entender o problema e muitas vezes perco muito tempo para fazer uma alteração simples. Existe uma frase que ouvi dos tempos do Smalltalk que dizia, se seu método não cabe na janelinha (aprox. 30 linhas) do ambiente, ele está grande demais. 

No seu caso, o que impede de ter o mesmo método mas com a seguinte idéia:

int capitalize( char *dst, char *src, int len ) {

numerosEPalavrasNumeradas(buffer);
letrasEAlgRomanos(buffer);
simbolosEAcentos(buffer);
preoposicoesEConectivos(buffer);
artigos(buffer);
abreviaturas(buffer);

}

Note que os métodos poderiam ser em inglês e com nomes mais ilustrativos.
Eu diria que você teria 3 vantagens diretas:
* Teria métodos que poderiam ser reusados;
* Teria um código mais limpo e simples de compreender;
* Manutenção ficaria localizada em partes que teriam menos efeitos colaterais.

--
Márcio Geovani Jasinski
Brno, Czech Republic
Mobile: +420 77317 5781

[Marcio Gil]

Eu entendo a idéia, mas veja que ao invés de termos uma função
executando uma ação bem específica (padronizar nomes ou títulos)
teríamos sete funções para fazer a mesma coisa. Não sei se quebrar
um programa em zilhões de minúsculos pedaços realmente leva a um
sistema de fácil manutenção, pois o efeito pode ser o contrário.
Isso depende do padrão adotado pela equipe de desenvolvimento, se
deve limitar o tamanho ou a complexidade das funções em 30 ou 300
linhas. Realmente não existe uma única alternativa de padrão de
código.

Eu sei que minha função pode ser melhorada, pois é a versão 1 feita
a alguns anos. Para começar eu eliminaria o "buffer" e colocaria a
palavra direto em "dst", talvez trocasse aqueles "strcmp(...) == 0
|| strcmp(...) == 0 || ..." por "strstr("DasDos...",...) != NULL",
etc. Mas o objetivo não era discutir a função (e muito menos o
emprego do autor), mas sim demonstrar a idéia de utilizar
comentários como uma espécie de subtítulos em um algorítmo.

[Márcio Geovani Jasinski]

Sim eu entendo os seus argumentos Márcio. Inclusive adicionaria o fato de que fazer a sua solução com várias funções leva bem mais tempo que fazer em um método. E como você disse, há cada ano que passa, o código seria melhorado se você ficasse sempre nesse problema. Também não quero figir do tópico que é comentários no código...

O que eu queria mostrar no exemplo é, se você tem um método composto por várias chamadas a outros métdodos, os comentários podem ser menos necessários. Para focar novamente no caso dos comentários, minha opinião é que comentários são úteis mas que devem ser usados de acordo com a necessidade.

Penso que existem 2 tipos de comentários, os internos e os de documentação. Um exemplo simples que encontrei:
http://www.cplusplus.com/reference/string/string/substr/

Para mim, funções assim e documentadas dessa forma me ajudam a saber o resultado sem ficar testando a função.
Dentre as coisas que eu gosto de saber para usar as funções: 

1. Como os argumentos vão se comportar (se o limite será inclusivo ou exclusivo, se vai ser alterado ou não, se precisa ser assim ou assado...);

2. Qual o resultado de um argumento ruim: exceção, retorna null, segmentation fault?

3. O que vai ser returnado ou o que será alterado no caso de argumentos por referência;

Eu evito comentários no meio do código uma vez que acho que eles podem ser evitados quando se usa métodos claros. Mas há casos em que isso é realmente relevante: eu não imagino a implementação de algoritmos de criptografia sem comentários internos para ajudar a entender melhor o problema.

[Raphael]

Concordo, eu particulamente acho muito bom, apesar de não ter o
costume de comentar a menos que o que eu esteja fazendo seja realmente
de dificil entendimento.

Comentarios no fonte são bons, excessões à parte.

On 27 jun, 10:32, Vanessa Leite <vanessinhaleite.cp.u...@gmail.com>
wrote:

> Eu manteria como está.:D
>
> E aprovo o sistema de comentários.
>
> Acho que comentários no código-fonte são tão bons, se não melhores que uma
> documentação.
>
> Claro que há casos e casos.
>
> Eu acredito que comentários em um código fonte podem ser escritos com a
> própria programação. Colocando nomes de variáveis, métodos e funções,
> claros, nos quais você entenda o que eles fazem, havendo apenas uma
> complementação com comentários.
>
> Existem fontes meus de maratona de tempos atrás (quando você tá numa
> maratona você não se preocupa em comentar código né?) que se eu pegar hoje,
> não sei oq cada coisa faz.. são variáveis com nomes de 'a' a 'z',
> independente de serem contadoras ou nao, além de funções com nomes
> fazTudo(), nada(), ou qualquerCoisa().
>
> Entregar um fonte assim para alguém é até sacanagem.
>
> =*
>

> 2009/6/27 Marcio Gil <marciom...@bol.com.br>

> Alfred Hitchcock<http://www.brainyquote.com/quotes/authors/a/alfred_hitchcock.html>

[Márcio Gil]

Concordo com você Jasinski, funções pequenas excluem a necessidade
de comentários não explicativos. Mas nem sempre é possível diminuir
tanto as funções, ou elas são complexas demais (como os de
criptografia). Um fator crítico nesta divisão pode ser a eficiência,
se um algoritmo deve ser o mais eficiente possível, mais chamadas a
funções podem torná-la um pouco mais lenta.

Outro ponto é que ter muitas funções espalhadas pelo código pode
dificultar um pouco acompanhar um algoritmo ou mesmo encontrar um
problema.

Lembrei de um outro tipo de comentário: os esquemáticos. Utilizava
muito para fazer relatórios em modo texto:

/*
Ref. Descrição Estoque...
0------7------------------------------38---------...
00.000 123456789012345678901234567890 ##0,000.000...
*/

Também utilizo para passar esquemas feitos no papel, que me ajudam a
elaborar um algoritmo, para o código.

Márcio Gil.

P.S.: por favor, não interprete meus argumentos como teimosia, numa
discussão costumo manter o contraditório com o fim de servir de
antítese.

---- Mensagem original ----
> De: Márcio Geovani Jasinski

[Thiago Adams]

Existem dois níveis de entendimento do código.

O primeiro nível não depende da implementação, ele se refere ao que a
função faz quais são as pré condições e o resultado final nos
operadores. Além disso saber como a função reporta erros.

No exemplo do Marcio Gil, mesmo com o comentário nada disso ficou
claro.

//Prepara a cadeia com as palavras em iniciais maiúsculas (char *)

int capitalize( char *dst, char *src, int len )

- O que é o retorno?
- Por que src não é cont?
- len é do src ou do dst?
- Prepada como? Qual eh o efeito disso?
- Posso passar null?

Então de qualquer maneira tem que se olhar para a implemementação.

O segundo tipo de coment'ario 'e ao que se referente a implementacao.
Muitos dos comentarios da implementacao ali cairam no caso 3 " funcoes
inline" e neste ponto eu concordo com o que o Marcio Jasinski disse.
Uma funcao tem que ser quebrada em partes e o tamanho dela tem que ser
40 linhas no maximo. Ela tem que ser quebrada de forma que cada parte
represente um conceito e que de preferencia seja independente.
Um exemplo da criacao de um conceito eh o seguinte:
Ao inves de usar por exemplo. getsize() == 0 'e melhor ter o conceito
IsEmpty.
Quando escrever o fonte, tente escrever somente conceitos uns sobre os
outros ao inv'es de codigo. Os conceitos basicos serao tao simples que
geralmente nao eh preciso comentario. Os conceitos mais elaborados sao
lidos em termos dos basicos.


Tamb'em ali tem o caso de explicar o que o fonte esta fazendo como por
exemplo:

// Ignora espaços iniciais
while (isspace(*src))
++src;

Mesmo sem o cometario iria ler: "Andar enquando for espaco"
Pegando este caso poderia ser criada a operacao TrimLeft, TrimRight,
Trim.
Achei que foi isso que faltou no fonte, ler a intenção de cada parte
sem ter que decifrar o codigo.

-x-

Apesar de estar advogando contra a maioria dos comentarios para
mostrar o meu ponto de vista, nada impede de se encontrar bom
comentarios em um fonte.
Na minha opnião um bom exemplo de comentário é o próprio padrão do C+
+. Muita da documentacao do padrao 'e o proprio arquivo de cabecalho.
(Alias, vou abrir um parenteses aqui para dizer que gosto do modelo do
C/C++ de se ter um header e uma implementacao separada. Isso ajuda a
organizar as ideias e ver a declaracao de uma forma limpa e compacta)
No padrao C++, geralmente as funcoes sao documentadas da seguinte
forma:

Requires: Pre-requisitos
Effects: O que vai acontecer quando a funcao for executada. Quem muda,
muda como?
Postconditions: O que se espera ter acontecido. o que se observa.
Throw: Quais excecoes sao lancadas

O problema de se ter uma documentacao tao boa no codigo fonte 'e o
tamanho. E os problemas praticos, atualizacao etc.
O equibrio disso tudo 'e nao fazer com que algo que eh para ser um
auxilio se transforme em um ruido ou informacao desatualizada ou
incorreta.

Alguns dos meus pontos sao:

-E' melhor ter um fonte claro do que ter um fonte complicado com
comentarios. Pensar como deixar o fonte claro antes de colocar um
comentario. A sua documentacao total geralmente vai ser seu fonte e
nao seu comentario, isto porque geralmente nao existe uma
especificacao.

- Nao comentar algo que se deva ter cuidado, que seja perigoso de se
fazer. Ao inves disso remova o perigo.

-Se nao estiver usando documentacao automatica, acho que vale a pena
nao comentar o obvio
GetName, SetName, GetSize, m_counter //contador etc..

- Nao comentar o que o codigo esta fazendo. for (i = 0; i < 4; i++) //
de 1 a 4..

- Acho que nao vale a pena colocar coisas do tipo: //constructor //
destructor etc //fonte que implementa a classe X

> > Mobile: +420 77317 5781- Ocultar texto das mensagens anteriores -
>
> - Mostrar texto das mensagens anteriores -

> P.S.: por favor, não interprete meus argumentos como teimosia, numa
> discussão costumo manter o contraditório com o fim de servir de
> antítese.

A pior discussão é aquela aonde tudo mundo concorda com tudo. :)

[Márcio Gil]

> -----Mensagem original-----
> De: Thiago Adams
>

> //Prepara a cadeia com as palavras em iniciais maiúsculas (char *)
> int capitalize( char *dst, char *src, int len )
>
> - O que é o retorno?
> - Por que src não é cont?
> - len é do src ou do dst?
> - Prepada como? Qual eh o efeito disso?
> - Posso passar null?
>

Perfeito Thiago, é mesmo preciso gastar um pouco de tempo
documentando esta parte.

> Quando escrever o fonte, tente escrever somente conceitos uns
> sobre os outros ao inv'es de codigo. Os conceitos basicos serao
> tao simples que geralmente nao eh preciso comentario. Os conceitos
> mais elaborados sao lidos em termos dos basicos.
>

Mas vamos supor que, na impossibilidade de se dividir um código em
vários pedaços, seja por causa de tempo ou desempenho ou qualquer
outro motivo, mesmo comentários óbvios podem facilitar a
decodificação do código?

Se você explica o funcionamento de um algoritmo apenas no header,
outra pessoa pode ter dificuldade de descobrir o que cada parte do
código faz. Mas se você indica no fonte, por meio de comentários, o
que cada parte do código representa, fica fácil entender o
algoritmo, e ao mesmo tempo, acompanhar no código a sua execução.

>
> Tamb'em ali tem o caso de explicar o que o fonte esta fazendo como
> por exemplo:
>
> // Ignora espaços iniciais
> while (isspace(*src))
> ++src;
>

A intenção não era explicar o código, mas explicar o algoritmo:

1º Remover os espaços iniciais;
2º Encontrar palavras:
a) Números ou palavras com números;
b) Palavras compostas somente de letras ou letras acentuadas;
c) Algarismos romanos;
3º Identificar preposições ou conectivos;
...

Por isso escolhi este exemplo, para tentar defender que mesmo
comentários aparentemente óbvios podem ser úteis.

> O problema de se ter uma documentacao tao boa no codigo fonte 'e o
> tamanho. E os problemas praticos, atualizacao etc.
> O equibrio disso tudo 'e nao fazer com que algo que eh para ser um
> auxilio se transforme em um ruido ou informacao desatualizada ou
> incorreta.
>

Aqui vou extrapolar um pouco: imagine ter uma obra de referência sem
títulos e subtítulos? Como você encontraria alguma coisa?

Outra coisa que devo notar é que o efeito obtido em se documentar um
monte de funções pequenas é o mesmo do meu código em comentar um
pedaço de código. E pode até aumentar o volume de comentários, pois
aí será necessário explicar os parâmetros, pré-condições,
pós-condições, retorno, etc. Neste caso, deixar de comentar uma
função por que seu nome deixa claro a sua intenção pode até ser
perigoso: o que é obvio para você pode não ser óbvio para outros.

[Thiago Adams]

On 29 jun, 12:19, Márcio Gil <marciom...@bol.com.br> wrote:
> > -----Mensagem original-----
> > De: Thiago Adams
>
> > //Prepara a cadeia com as palavras em iniciais maiúsculas (char *)
> > int capitalize( char *dst, char *src, int len )
>
> > - O  que é o retorno?
> > - Por que src não é cont?
> > - len é do src ou do dst?
> > - Prepada como? Qual eh o efeito disso?
> > - Posso passar null?
>
> Perfeito Thiago, é mesmo preciso gastar um pouco de tempo
> documentando esta parte.
>
> > Quando escrever o fonte, tente escrever somente conceitos uns
> > sobre os outros ao inv'es de codigo. Os conceitos basicos serao
> > tao simples que geralmente nao eh preciso comentario. Os conceitos
> > mais elaborados sao lidos em termos dos basicos.
>
> Mas vamos supor que, na impossibilidade de se dividir um código em
> vários pedaços, seja por causa de tempo ou desempenho ou qualquer
> outro motivo, mesmo comentários óbvios podem facilitar a
> decodificação do código?

Se eles podem facilitar? Talvez. Mas antes deve ser considerado
escrever em forma de código.
Pegando o exemplo:
..
if (k > 0 && dst[k-1] != '\n' && src[i] != '\0'
&& src[i] != '\r' && src[i] != '\n' && isspace(src[i])
&& (strcmp(buffer,"Ao") == 0 || strcmp(buffer,"Al") == 0
|| strcmp(buffer,"Com") == 0 || strcmp(buffer,"Con") == 0
|| strcmp(buffer,"Da") == 0 || strcmp(buffer,"Das") == 0
|| strcmp(buffer,"De") == 0 || strcmp(buffer,"Di") == 0
|| strcmp(buffer,"Do") == 0 || strcmp(buffer,"Dos") == 0
|| strcmp(buffer,"Del") == 0 || strcmp(buffer,"Von") == 0
|| strcmp(buffer,"E") == 0 || strcmp(buffer,"Et") == 0
|| strcmp(buffer,"Y") == 0 || strcmp(buffer,"And") == 0
|| strcmp(buffer,"Und") == 0 || strcmp(buffer,"Em") == 0
|| strcmp(buffer,"Na") == 0 || strcmp(buffer,"Nas") == 0
|| strcmp(buffer,"No") == 0 || strcmp(buffer,"Nos") == 0))
{ // Preposição ou conectivo
}
....
É mais simples criar uma função e remover o comen'tario

BOOL IsPreposition(char char* str)
{
}

O que você tinha em mente era:

Se s é preposicao entao..

Que pode ser escrito

if (IsPreposition(s)) { ...}

Eu não acho que seja o mesmo efeito. Como mostrei no exemplo do
IsPreposition, o conceito é tao simples que nao precisa ser comentado.
O IsPreposition fica independente, isolado, o algoritmo pode ser
escrito em menos linhas e fica de mais facil leitura.

[Rodrigo (skhaz)]

Ou usar expressões regulares =)

2009/6/29 Thiago Adams <thiago...@gmail.com>:

--
http://www.skhaz.com/