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.
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.
É 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
On Jun 25, 9:20 pm, Blabos de Blebe <bla...@gmail.com> wrote:
> 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.
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.
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".
> 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.
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 */
> 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.
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í.
> 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".
> > 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.
> 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 */
> 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.
>> 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".
>> > 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.
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.
> 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.
<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
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.
> 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.
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
> 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
> > 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.
> 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
>> 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
>> > 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.
>> 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
>>> 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
>>> > 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.
> 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
#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 - 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 - 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.
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:
>>> #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.
> 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:
>>>> #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.
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>
> > 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.
> > > 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.
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.
> 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:
> > 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>
> > > 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.
> > > > 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.
-- 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<http://www.brainyquote.com/quotes/authors/a/alfred_hitchcock.html>
- "Television has brought back murder into the home - where it
belongs."
|
