Código bom fala por si só?

[Rafael Noronha]

Esta semana escrevi no blog sobre algo que considero um dos segredos
para se dominar "a arte de escrever software".

Código bom, de verdade, precisa falar por si só.

Se um programador vê o seu código pela primeira vez e não entende o
que está acontecendo, você está com problemas.

Gostaria de saber se alguém discorda do potencial desta prática, ou
tem algo a acrescentar.

Particularmente gosto muito deste tipo de técnica.
Acho que a maioria aqui deve zelar pelo código tanto quanto eu. Ou
quase tanto como eu. =D

Além de ser uma técnica legal acho que tem tudo a ver com a história
das linguagens de programação.

Se expressividade não fosse importante (por motivos óbvios) a gente
ainda escreveria em linguagem de máquina.

Hoje temos aí Ruby, que coloca linguagens como C# e Java no chinelo ao
falarmos em expressividade de código.

Segue o link do post:
http://rafanoronha.net/en/explicit-intent/

[Raphael Molesim]

Disse tudo!

Ruby = Expressividade

É diferente quando uma linguagem é feita com esta intenção.

[Rodrigo Braga]

Concordo, acho bastante interessante!

Python ilustra isso muito bem... e passa bastante a idéia de
"linguagem natural", onde ler um código bem escrito é "quase como" ler
um texto qualquer (de forma estruturada).

Mas isso é uma iniciativa que deve partir diretamente do
desenvolvedor, uma ação natural dele... que deve manter-se preocupado
com isso; afinal a excelência é sobretudo um hábito.

2009/9/4 Raphael Molesim <raph...@infoserver.com.br>:

--
Att.,
Rodrigo Braga

[daniel queiroz]

Tive um chefe que desestimulava ao máximo o uso de comentários, ele
afirmava que código bem escrito era auto-descritivo. Era só olhar e
entender. Tem seus riscos, mas eu concordo com essa abordagem, já vi
códigos ridicularmente comentados, como o exemplo abaixo:

//Imprime na tela
Console.Writeline("Hello World");

Sou totalmente contra os comentários que abordam aspectos referentes a
linguagem, e não a regra de negocio.

Regards

Em 04/09/09, Rodrigo Braga<rbr...@gmail.com> escreveu:

[Guilherme Oenning]

O livro Clean Code do Uncle bob tem um capítulo sobre comentários, ele
mostra os cenários onde o uso de comentários é recomendado, bem poucos se
comparado com cenários onde você NÃO deve usar. Ele inclusive aborda esses
comentários sobre regra de negócio, e geralmente você não precisa.

[]'s
Guilherme Oenning

-----Mensagem original-----
De: dotnetar...@googlegroups.com
[mailto:dotnetar...@googlegroups.com] Em nome de daniel queiroz
Enviada em: sexta-feira, 4 de setembro de 2009 09:33
Para: dotnetar...@googlegroups.com
Assunto: [dotnetarchitects] Re: Código bom fala por si só?

[Emmanuel G. Brandão]

Eu já vi:

//retorna x
return x;

Brandão, Emmanuel G.
CSM
blog.egomesbrandao.net

___________________________________
Ao encaminhar esta mensagem, por favor:
1 - Apague meu endereço eletrônico;
2 - Apague também os endereços dos amigos que receberam juntamente com você a mensagem, antes de enviar;
3 - Encaminhe como Cópia Oculta (Cco ou BCc) aos seus destinatários. Dificulte assim a disseminação de vírus, spams e banners.

2009/9/4 daniel queiroz <daniell...@gmail.com>

[Victor Cavalcante]

Emmanuel,

Aí forçou em...

//se x for maior que 0
if (x>0)

heheheheh,

Victor Cavalcante

2009/9/4 Emmanuel G. Brandão <egomes...@gmail.com>

[higor.cesar]

Fala Galera, essa é uma questão recorrente. O código bom na maioria
dos casos fala por si. No entanto
como obter esta clareza? o m.Fowler em seu livro sobre refatoração
fala que métodos devem
ser usados no lugar de comentários. ele mostra alguns exemplos que eu
não criaria métodos. Quanto aos comentários
acho uma boa iniciativa, principalmente para reportar contratos e
exceções de um determinado método.O problema de
comentar é a manutenção, já trabalhei em diversos sistemas onde o
código era alterado e os comentários ficavam obsoletos.
Bem.acho que bom senso é o mais importante com todas essas
possibilidades.

Higor César
www.higorcesar.com

On 4 set, 11:49, Victor Cavalcante <vic...@cavalcante.net> wrote:
> Emmanuel,
>
> Aí forçou em...
>
> //se x for maior que 0
> if (x>0)
>
> heheheheh,
>
> Victor Cavalcante
>

> 2009/9/4 Emmanuel G. Brandão <egomesbran...@gmail.com>

>
> > Eu já vi:
>
> > //retorna x
> > return x;
>
> > Brandão, Emmanuel G.
> > CSM
> > blog.egomesbrandao.net
>
> > ___________________________________
> > Ao encaminhar esta mensagem, por favor:
> > 1 - Apague meu endereço eletrônico;
> > 2 - Apague também os endereços dos amigos que receberam juntamente com você
> > a mensagem, antes de enviar;
> > 3 - Encaminhe como Cópia Oculta (Cco ou BCc) aos seus destinatários.
> > Dificulte assim a disseminação de vírus, spams e banners.
>

> > 2009/9/4 daniel queiroz <daniellquei...@gmail.com>

>
> >>  Tive um chefe que desestimulava ao máximo o uso de comentários, ele
> >> afirmava que código bem escrito era auto-descritivo. Era só olhar e
> >> entender. Tem seus riscos, mas eu concordo com essa abordagem, já vi
> >> códigos ridicularmente comentados, como o exemplo abaixo:
>
> >> //Imprime na tela
> >> Console.Writeline("Hello World");
>
> >> Sou totalmente contra os comentários que abordam aspectos referentes a
> >> linguagem, e não a regra de negocio.
>
> >> Regards
>
> >> Em 04/09/09, Rodrigo Braga<rbr...@gmail.com> escreveu:
>
> >> > Concordo, acho bastante interessante!
>
> >> > Python ilustra isso muito bem... e passa bastante a idéia de
> >> > "linguagem natural", onde ler um código bem escrito é "quase como" ler
> >> > um texto qualquer (de forma estruturada).
>
> >> > Mas isso é uma iniciativa que deve partir diretamente do
> >> > desenvolvedor, uma ação natural dele... que deve manter-se preocupado
> >> > com isso; afinal a excelência é sobretudo um hábito.
>

> >> > 2009/9/4 Raphael Molesim <rapha...@infoserver.com.br>:

[Leonardo Neves]

Não sei se hoje em dia está assim, mas quando fiz faculdade (acabei a 2 anos atrás) os professores frisavam muito na questão de ter um código bem comentado. Inclusive esse tipo de comentário ridículo que o Emannuel e o Victor colocaram era visto como "boa prática de desenvolvimento".

 Ja trabalhei com um gerente que dizia que não via muito sentido em documentação (documento de visão, etc)... Que um código bem documentado "era equivalente" a documentação abrangente.

--
Leonardo Neves

[Emmanuel G. Brandão]

Pois é, mas o engraçado foi quando questinei o programador por que ele estava fazendo isso, e ele me disse que como ele contribuia com código para softwares livre eles pedem que tenha o máximo de comentários, pois a maioria não são exatamente programadores... (!!!)
Oras bolas, se não são programadores o que os caras estão fazendo alterando código fonte??

Brandão, Emmanuel G.
CSM
blog.egomesbrandao.net

___________________________________
Ao encaminhar esta mensagem, por favor:
1 - Apague meu endereço eletrônico;
2 - Apague também os endereços dos amigos que receberam juntamente com você a mensagem, antes de enviar;
3 - Encaminhe como Cópia Oculta (Cco ou BCc) aos seus destinatários. Dificulte assim a disseminação de vírus, spams e banners.

2009/9/4 Victor Cavalcante <vic...@cavalcante.net>

[Henry Charriere]

Recomendo o livro Code Comple de Steve McConnel, no Cap. 32 Documentado o Código Automaticamente, ele trata de todos esses assuntos. Muito bom acabei de ler.



Att,
Henry Charriere C. Nascimento
Talk: henry.charriere
Skpe: henry.charriere
MSN: henryt...@hotmail.com

[higor.cesar]

Ai galera, falando em documentação ainda temos os testes
automatizados..
uma definição legal que eu vi para testes é que eles são documentação
executável.

www.higorcesar.com

On 4 set, 12:48, Henry Charriere <henry.charri...@gmail.com> wrote:
> Recomendo o livro Code Comple de Steve McConnel, no Cap. 32 Documentado o
> Código Automaticamente, ele trata de todos esses assuntos. Muito bom acabei
> de ler.
>
> Att,
> Henry Charriere C. Nascimento
> Talk: henry.charriere
> Skpe: henry.charriere

> MSN: henrytele...@hotmail.com

>
> 2009/9/4 Emmanuel G. Brandão <egomesbran...@gmail.com>
>

> > Pois é, mas o engraçado foi quando questinei o programador por que ele
> > estava fazendo isso, e ele me disse que como ele contribuia com código para
> > softwares livre eles pedem que tenha o máximo de comentários, pois a maioria
> > não são exatamente programadores... (!!!)
> > Oras bolas, se não são programadores o que os caras estão fazendo alterando
> > código fonte??
>
> > Brandão, Emmanuel G.
> > CSM
> > blog.egomesbrandao.net
>
> > ___________________________________
> > Ao encaminhar esta mensagem, por favor:
> > 1 - Apague meu endereço eletrônico;
> > 2 - Apague também os endereços dos amigos que receberam juntamente com você
> > a mensagem, antes de enviar;
> > 3 - Encaminhe como Cópia Oculta (Cco ou BCc) aos seus destinatários.
> > Dificulte assim a disseminação de vírus, spams e banners.
>
> > 2009/9/4 Victor Cavalcante <vic...@cavalcante.net>
>
> > Emmanuel,
>
> >> Aí forçou em...
>
> >> //se x for maior que 0
> >> if (x>0)
>
> >> heheheheh,
>
> >> Victor Cavalcante
>

> >> 2009/9/4 Emmanuel G. Brandão <egomesbran...@gmail.com>

>
> >> Eu já vi:
>
> >>> //retorna x
> >>> return x;
>
> >>> Brandão, Emmanuel G.
> >>> CSM
> >>> blog.egomesbrandao.net
>
> >>> ___________________________________
> >>> Ao encaminhar esta mensagem, por favor:
> >>> 1 - Apague meu endereço eletrônico;
> >>> 2 - Apague também os endereços dos amigos que receberam juntamente com
> >>> você a mensagem, antes de enviar;
> >>> 3 - Encaminhe como Cópia Oculta (Cco ou BCc) aos seus destinatários.
> >>> Dificulte assim a disseminação de vírus, spams e banners.
>

> >>> 2009/9/4 daniel queiroz <daniellquei...@gmail.com>

>
> >>>>  Tive um chefe que desestimulava ao máximo o uso de comentários, ele
> >>>> afirmava que código bem escrito era auto-descritivo. Era só olhar e
> >>>> entender. Tem seus riscos, mas eu concordo com essa abordagem, já vi
> >>>> códigos ridicularmente comentados, como o exemplo abaixo:
>
> >>>> //Imprime na tela
> >>>> Console.Writeline("Hello World");
>
> >>>> Sou totalmente contra os comentários que abordam aspectos referentes a
> >>>> linguagem, e não a regra de negocio.
>
> >>>> Regards
>
> >>>> Em 04/09/09, Rodrigo Braga<rbr...@gmail.com> escreveu:
>
> >>>> > Concordo, acho bastante interessante!
>
> >>>> > Python ilustra isso muito bem... e passa bastante a idéia de
> >>>> > "linguagem natural", onde ler um código bem escrito é "quase como" ler
> >>>> > um texto qualquer (de forma estruturada).
>
> >>>> > Mas isso é uma iniciativa que deve partir diretamente do
> >>>> > desenvolvedor, uma ação natural dele... que deve manter-se preocupado
> >>>> > com isso; afinal a excelência é sobretudo um hábito.
>

> >>>> > 2009/9/4 Raphael Molesim <rapha...@infoserver.com.br>:

[Gustavo Melo]

Um código bem escrito no meu ver deve focar nos padrões DSL e Ubiquitous Language.

Assim fica uma linguagem de domínio bem interpretada para os desenvolvedores quanto para o cliente.

2009/9/4 higor.cesar <higo...@gmail.com>

--
Analista Desenvolvedor
www.espacodj.com

[Rafael Noronha]

Gustavo,

Acho que é mais ou menos por aí.
Tem que refletir o negócio mesmo, e se possível chegando perto de uma
dsl (nem sempre é possível, principalmente em linguagens como c#).

Segue um objeto de negócio que modelei recentemente:
http://pastie.org/590746

Rafael Noronha
http://rafanoronha.net/

[Juan Pedro A. Lopes]

http://pastie.org/606476
 

principalmente em linguagens como c#

O problema do C# certamente não é a linguagem.

[Giovanni Bassi]

A refatoração para métodos é muito importante. É um assunto que costumo tocar nas consultorias, mas geralmente só quando a empresa já está pegando o jeito da coisa, porque corre o risco de soar inútil.

Acho fundamental aplicar o Single Responsability Principle também para os métodos. Cada método deve trabalhar com um só nivel de abstração. Se o nível passar do primeiro, passa o trabalho para outro método.

 

Ah, e comentários são malignos. Há tempos que evito qualquer tipo de comentário. Se você escreveu um comentário é porque seu código não é legível. Ou deu um nome errado numa variável, ou precisa explicitar mais um conceito, e por aí vai. Se você está comentando seu próprio código, é porque não está mais entendendo o que fez, ou já entendeu que está tão enrolado, que o próximo não vai entender.

[]'s

Giovanni Bassi
Microsoft MVP, MCSD, MCPD, CSM
Arquiteto de software
http://www.giovannibassi.com

2009/9/4 higor.cesar <higo...@gmail.com>

[Giovanni Bassi]

Sem dúvida. Testes SÃO documentação. E você pode executar. Quer coisa melhor?

[]'s

Giovanni Bassi
Microsoft MVP, MCSD, MCPD, CSM
Arquiteto de software
http://www.giovannibassi.com

2009/9/4 higor.cesar <higo...@gmail.com>

[Giovanni Bassi]

Juan, é verdade!

 

Porque será que não é tão comum que programadores de C# pensem em APIs nesse estilo, mais fluente? É cultura da comunidade Ruby, ou será que o linguagens como o Ruby levam a um estilo mais legível?

[]'s

Giovanni Bassi
Microsoft MVP, MCSD, MCPD, CSM
Arquiteto de software
http://www.giovannibassi.com

2009/9/4 Juan Pedro A. Lopes <zero...@gmail.com>

[Juan Pedro A. Lopes]

Fluent interfaces estão finalmente virando moda em C#. O Fluent NHibernate é o melhor exemplo que consigo encontrar pra esse caso. Assim como a lista de discussão que se tornou a Issue 18 do projeto Migrator.Net. Inclusive, eu mesmo comecei a trabalhar numa interface fluente pro projeto citado.

O problema maior, na minha opinião, é o débito técnico da grande massa de desenvolvimento .NET. Na comunidade Ruby isso é menos comum. Mal comparando, Ruby é a Suécia e .NET é o Brasil, nesse quesito.

2009/9/5 Giovanni Bassi <gig...@gmail.com>

[Denis Ferrari]

Penso que o código fonte deva ser a própria documentação do software
(juntamente com os testes).

Acho muito pertinente o comentário do Giovanni que a necessidade de
comentários mostra que o código possui problemas de legibilidade,
refatoração e/ou divisão de responsabilidades, porém, existem outros
fatores.

Quando escrevo testes busco como diretriz a legibilidade, de forma que
quem for utilizar o artefato testado entenda sua utilização e como o
mesmo foi construído (Uso TDD), porém, legibilidade em código pode ser
relativo, me deparo em várias situações onde precisaria criar métodos,
porém, indireções algumas vezes reduzem a legibilidade do código no
ponto de vista de quem está aprendendo o negócio. Outro fator é a
experiência de quem está lendo o código, acredito que comentar um
return x é o cúmulo, porém, acho ideal prezar por escritas mais
simples como usar um if normal no lugar de um operador ternário.

Em um projeto que estou trabalhando atualmente precisamos substituir
um membro da equipe por um menos experiênte, o que deixou claro a
importância de um códilo legível, essa situação não é singular pois
mesmo alguns desenvolvedores experiêntes tem problemas de entender
algumas instruções escritas por arquitetos.

Não vou entrar no mérito de discutir qual linguagem é melhor ou pior,
acho que essa é a menor questão, qualquer linguagem pode ser escrita
com código legível, basta o desenvolvedor ou arquiteto ter no coração
que essa é uma boa prática.

Denis Ferrari
Arquiteto de Software
http://desenvolvimento.denisferrari.com/

On 4 set, 21:21, "Juan Pedro A. Lopes" <zerova...@gmail.com> wrote:
> Fluent interfaces estão finalmente virando moda em C#. O Fluent

> NHibernate<http://www.fluentnhibernate.org>é o melhor exemplo que

> consigo encontrar pra esse caso. Assim como a lista
> de discussão que se tornou a Issue 18 do projeto

> Migrator.Net<http://code.google.com/p/migratordotnet/issues/detail?id=18>.

> Inclusive, eu mesmo comecei a trabalhar numa interface

> fluente<http://code.google.com/p/migratordotnet-fluent/>pro projeto

> citado.
>
> O problema maior, na minha opinião, é o débito técnico da grande massa de
> desenvolvimento .NET. Na comunidade Ruby isso é menos comum. Mal comparando,
> Ruby é a Suécia e .NET é o Brasil, nesse quesito.
>
> 2009/9/5 Giovanni Bassi <gig...@gmail.com>
>
> > Juan, é verdade!
>
> > Porque será que não é tão comum que programadores de C# pensem em APIs
> > nesse estilo, mais fluente? É cultura da comunidade Ruby, ou será que o
> > linguagens como o Ruby levam a um estilo mais legível?
>
> > []'s
>
> > Giovanni Bassi
> > Microsoft MVP, MCSD, MCPD, CSM
> > Arquiteto de software
> >http://www.giovannibassi.com
>

> > 2009/9/4 Juan Pedro A. Lopes <zerova...@gmail.com>

[Rafael Noronha]

Juan,

Concordo que é possível escrever um código mais expressivo em C#,
através de interfaces fluentes.
Eu mesmo já fiz isto:
http://rafanoronha.net/en/validation-specs-with-nhibernate-validator/

Mas acredito ser senso comum a maior dificuldade de se chegar a um
código mais expressivo com c# do que com linguagens mais "leves" como
Ruby, por exemplo.

Rafael Noronha
http://rafanoronha.net/

[Juan Pedro A. Lopes]

O que você chama de "leve", eu chamo de "permissiva". Obviamente o Ruby vai dar mais ferramentas de expressão que o C#, afinal, é uma linguagem dinâmica. Mas esse obviamente não é o ponto. O que eu quero dizer que se alguém fizesse qualquer menção a sintaxes fluentes a uns 2 anos atrás, muita gente do mundo .NET iria torcer o nariz. Hoje em dia, isso está ficando cada vez mais comum. Acredito (e espero) que essa moda venha para ficar.

2009/9/6 Rafael Noronha <rafan...@gmail.com>

[Ricardo Cunha]

Oi,

 

Acredito que papelada demais só atrapalha, precisamos de documentação prática.

 

Porém não acho que comentários são malignos. Acredito que são desnecessários em situações óbvias, mas nunca sinonimo de que seu código não é legível.

 

Entendo que algumas metodologias[DDD], sugerem uma programação mais expressiva[orientada ao domínio do problema], contudo como prever situações aonde você é o programador e o analista de negócios, dba, tester, etc, etc, etc.

 

Sendo assim numa eventual falta sua (saída da empresa, doença, acidente, morte, sei lá) nada melhor do que uma boa introdução(via comentário, por que não?) de um determinado objeto, método ou sequencia de execuções, explicando sua origem e seu objetivo final.

 

Em minhas equipes costumo incentivar uma programação democratica, assim todos conhecem um pouco de cada tarefa que está sendo executada e o número excessivo de comentários no código torna-se desnecessário, contudo incentivo SIM a comentarem quando sentirem necessidade, e nem por isso digo, ou sinto, que são maus programadores ou que o projeto está comprometido.

 

[]'s

 

Ricardo Simões

 

 

2009/9/5 Giovanni Bassi <gig...@gmail.com>

[Giovanni Bassi]

Ricardo,

 

Você não acha que se o programador precisa comentar é porque não está claro o que o código está fazendo?

[]'s

Giovanni Bassi
Microsoft MVP, MCSD, MCPD, CSM
Arquiteto de software
http://www.giovannibassi.com

[Giovanni Bassi]

Juan,

 

É verdade. É bom lembrar que até hoje os programadores de C# torcem o nariz para a liberdade que o VB coloca.

Agora que o Ruby é cool, todo mundo fala que dinamismo é legal, mas muitos ainda reclamam do VB. Não faz o menor sentido.

[]'s

Giovanni Bassi
Microsoft MVP, MCSD, MCPD, CSM
Arquiteto de software
http://www.giovannibassi.com

2009/9/7 Juan Pedro A. Lopes <zero...@gmail.com>

[Rodrigo Braga]

Essa questão do comentário talvez traga consigo até uma questão
"histórica/cultural" onde comentar iria "enriquecer" o código, quando
na verdade não é necessariamente assim.

Porém código "expressivo" pode ser relativo (o seu expressivo pode não
ser tão expressivo assim), talvez pequenos comentários introdutórios
em partes mais sensíveis seja válido sim.

Como exeplificaram antes, comentar "return foo" com "retorna foo" é
realmente exagero, mas talvez algumas pessoas o façam pela questão que
citei acima; mas dependendo da complexidade do projeto, regras e
afins, um comentário "introdutório" suscinto, direto e objetivo ao
menos mal não irá fazer.

Talvez um dos problemas seja justamente o bom senso em determinar onde
é crítico o suficiente para se fazer o tal comentário.

Uma coisa que não lembro de terem comentado e que pode minimizar ou
mesmo anular a necessidade de comentários nos códigos "mais
expressivos" é o uso do "summary" (similar ao docstring no python ou
javadoc no java, não lembro se o nome é esse mesmo) que permitir
documentarmos o código e pode ser usado em ferramentas para geração de
documentação e talz.


2009/9/9 Giovanni Bassi <gig...@gmail.com>:

> Ricardo,
>
> Você não acha que se o programador precisa comentar é porque não está claro
> o que o código está fazendo?
> []'s
>
> Giovanni Bassi
> Microsoft MVP, MCSD, MCPD, CSM
> Arquiteto de software
> http://www.giovannibassi.com
>
>

> 2009/9/9 Ricardo Cunha <rsc...@gmail.com>

--
Att.,
Rodrigo Braga

[Ricardo Cunha]

Oi Giovanni,

 

Vejo 3 situações para os comentários:

 

1. Comentário desnecessário. Está tão claro que não precisa nem comentar.

2. Comentário para POG. Está tão difícil de entender que precisa comentar.

3. Comentário vital. Como vou sair de férias e não tenho nenhuma documentação formal sobre este processo, que classifiquei como complexo, vou criar uma introdução sucinta, mas clara e expressiva, nas classes e métodos para que a pessoa que vá me substituir saiba que fui eu que fiz e tenha uma idéia rápida sobre o código que vai dar manutenção, afinal de contas este programador(a) não vai ter tempo de ficar estudando meu código para ser mais ágil quando precisar fazer uma alteração inesperada.

 

[]'s

 

Ricardo Simões

 

 

2009/9/9 Rodrigo Braga <rbr...@gmail.com>

[Pepeu]

Concordo contigo Ricardo.

E digo mais, acho que o numero de comentários está mais ligado a complexidade da regra de negocio do que qualquer outra coisa. Alguem aí já trabalhou com sistema fiscal? :D

 

Abraços,
Pedro

[Pedro Reys]

2009/9/9 Ricardo Cunha <rsc.net@gmail.com>

3. Comentário vital. Como vou sair de férias e não tenho nenhuma documentação formal sobre este processo, que classifiquei como complexo, vou criar uma introdução sucinta, mas clara e expressiva, nas classes e métodos para que a pessoa que vá me substituir saiba que fui eu que fiz e tenha uma idéia rápida sobre o código que vai dar manutenção, afinal de contas este programador(a) não vai ter tempo de ficar estudando meu código para ser mais ágil quando precisar fazer uma alteração inesperada.

 

[]'s

 

Ricardo Simões

 

 

Ricardo,

 

Primeiro, voce nao precisa comentar o codigo para dizer, para quem quer que seja, que voce eh o autor. O controlador de versao fara isso por voce :)

 

E eh justamente tendo um codigo expressivo, utilizando DDD por exemplo, que vc dara agilidade na manutencao do seu codigo.

 

Alem do perigo, e da alta probabilidade, do seu comentario nao estar sincronizado com o seu codigo. Quantas vezes nao nos deparamos com comentarios que jah nao tem mais nada a ver com o que esta realmente implementado.