Sobre comentários no código :::: Rodrigo Strauss :: www.1bit.com.br
Sobre comentários no código
Esse é mais um post que começou como resposta para um comentário, mas cresceu demais e aprendeu a falar :-). Eu já estava a muito tempo ensaiando para escrever algo sobre a importância de comentar muito bem o código, e agora vou aproveitar o gancho para passar minhas opniões e gerar mais discussão sobre o assunto. Esse post começou como uma resposta para os comentários em "Programando direito com Slashdot".
Minha teoria é simples:
Você consegue fazer um script com 10 linhas de código que remove todos os comentários dos arquivos, se você não gosta de ler comentários. Agora eu quero ver você fazer um script que coloque os comentários de acordo com o que você estava pensando...
Comente tudo que puder, o mais explicado possível, se você pecar pelo excesso é só apagar os comentários depois. Os comentários são essenciais para saber qual idéia você teve na hora de desenvolver uma rotina ou algoritmo. Eu sou um programador C++, algumas vezes virtuoso, leio assembly com relativa facilidade, e não acho que código, em qualquer linguagem, seja claro. Colocar um comentário em uma expressão "variavel +=2;" não é exagero. Qualquer um percebe que você está somando 2 ao valor da variável, o que importa é dizer porque você está somando 2 e como isso causa impacto no restante do seu programa.
Comentar o código não gasta tempo a mais, faz parte do processo de desenvolvimento. Se você não coloca comentários no seu código, está pulando um parte importante desse processo, está fazendo pela metade. Pode parecer radical, mas eu levei alguns anos para perceber a importância disso, porque já dei manutenção em código bem comentado e código sem comentários. A diferença do tempo que você leva para entender o código e fazer as mudanças necessárias é absurda. Comentar código economiza tempo e dinheiro. Quem nunca se perguntou "o que esse cara queria fazer aqui"?
Se alguém aqui já teve oportunidade de ver o fontes do kernel do Windo^H^H^H^H^H^H^H^H^H^H^H^H^H^H^H^H os samples do DDK do Windows, sabe a diferença que faz um código bem comentado e bem organizado. Eu sinto muita diferença no meu trabalho quando vou dar manutenção em um código da equipe antiga (sem comentários) e da equipe atual (bem comentado). Posso garantir que, muitas vezes, o tempo para correção de um bug em um código bem comentado é menos da metade do tempo que se leva para corrigir um bug em um código sem comentários. Escrever código mais claro ajuda muito, mas não resolve o problema. O ideal é código claro e comentado. Se as empresas soubessem o quanto isso abaixa o custo de desenvolvimento, iam parar de pensar só em metodologia e pensariam um pouco mais em melhorar o código e a capacidade técnica de quem o escreve...
Existe sim o risco dos comentários ficarem errados com o tempo, alguém pode modificar o funcionamento de alguma coisa e deixar o comentário antigo. Sim, da mesma forma que seu software pode ter um bug. Esse é um risco pequeno perto dos grandes ganhos que um código bem comentado gera. Sem comentários, se você ficar 6 meses sem mexer no projeto e esquecer como ele funciona, vai ter que entender o código todo novamente (ou ler a documentação, que também pode estar desatualizada). Se você tiver bons comentários, toda vez que você for mudar alguma coisa, por mais que o intervalo seja longo, você terá um ponto de início. Sem comentários você tem um monte de código. E como eu disse - e torno a dizer - nenhum código, em nenhuma linguagem, é claro. Qualquer sistema que seja mais complexo do que um Hello World não é claro. Você pode achar claro enquanto faz, mas quem vem depois de você não achará, seja por falta de conhecimento da regra de negócio, ou mesmo falta de conhecimento na linguagem ou ambiente de programação.
Comentar o código é de suma importância, e isso deve ser pensado e conversado antes de tentar implementar qualquer metodologia. Comentar o código é um processo rápido, não traumático e resolve muitos problemas. Isso traz grandes vantagens a curto prazo e é muito mais barato e fácil do que implementar uma metodologia. É uma coisa que você pode começar hoje, agora, não depende de aprovação de gerente nenhum, não depende da má vontade do setor administrativo ou financeiro. Além de fazer um bem para empresa comentando bem o seu código, você fará um grande bem para você, pois terá bem menos dor de cabeça quando precisar fazer uma alteração em um sistema 4 anos depois. E a gente sabe que isso acontece.
Em 29/11/2005 18:00, por Rodrigo Strauss
Wanderley Caloni Jr | website | em 29/11/2005 | #
Vale meu comentário do artigo que iniciou isso: quanto menos óbvio, cuide melhor dos comentários.
Mas é importante o que Strauss disse: "você pode achar claro enquanto faz". Isso acontece todo o tempo, é óbvio que seja claro o código que se está mexendo naquele exato momento. Menos óbvio será na semana que vem, e menos ainda daqui a um ano.
E da mesma maneira que código organizado ajuda - e comentado é ainda melhor - deve-se organizar os comentários também, de maneira que código e comentários convivam harmoniosamente.
Por último, fazer manutenção em um código comentado significa fazer manutenção dos dois: código e comentários. Pensar dessa forma evita que existam comentários desatualizados.
Leonardo Stabile Prates | e-mail | em 29/11/2005 | #
concordo em partes... prefiro comentar blocos de codigo do a comentar linhas individuais, atualmente as IDEs fornecem feramentas suficientes para explicar detalhes individuais de linhas de codigo (ex: eu jogo o mouse em cima de uma funcao e abre um popup com o cabecalho dela, eh claro, desde q vc comente funcao a funcao)
no caso do "variavel += 2" a propria linha ja constitui um erro de desenvolvimento: oq eh "2"?! de onde ele surgiu?! nao seria melhor criar uma macro pra explicar o numero magico?!
"#define DESVIO_CALCULO 2"....
"const int DESVIO_CALCULO = 2;" (vamos fazer direito ehehhe)
de qqer forma, concordo plenamente com a importancia do comentario, mas explicando o conceito, e nao detalhes tecnicos da implementacao, a menos q sejam relevantes.
"Você pode achar claro enquanto faz"
sem duvida, aposto q ja aconteceu com todo mundo eheh
no caso dos codigos da microsoft, tb curto o estilo deles, a metrica, mesmo odiando notacao hungara. no caso de codigos gnu o codigo eh mto mais esperto, mas o problema eh outro, q por sinal eu acho pior: siglas magicas!! "get_rhe_she_feh()"... isso eh desumano...
Fabricio Ferreira | e-mail | em 02/12/2005 | #
Como eu acho que minha frase foi o estopim para este artigo...
O maior problema que vejo com comentários no código é que muitas vezes ele atrapalha a leitura do próprio código.
Se a IDE tivesse um recurso do tipo "Hide Comments", ou "Comment Outlining" seria uma grande ajuda.
[Apaga o comment anterior...analfabetismo total]
Como acho que minha frase foi o estopim para este artigo, vale uma réplica:
O maior problema que enfrento com os comentários, é o fato de que muitas vezes eles atrapalham a leitura do código. São muito extensos, não dizem quase nada. Sem contar os artistas ASCII, que fazem obras de arte com caracteres.
Hugo | em 07/12/2005 | #
Melhor do que comentários as vezes só a documentação gerada por eles por um doxygen da vida... vide a documentação da Qt e da KDElibs, que são ótimas por sinal... porém é documentação da API, e não do código, o que por mais bizarro que pareça é diferente =]
Murtog | website | e-mail | em 07/12/2005 | #
Eu, admito, sou um comentário-maníaco, escrevo comentários sempre e estou sempre aperfeiçoando eles. Apesar de que uns tempos para cá eu estar reduzindo o número deles, tentando chegar num meio termo. Que, como disse o colega, não chege a atrapalhar a leitura do código.
Abraços, ah, seria legal você continuar esse tipo de artigo, discutindo modos de programação: nomeclaturas, estruturas de classes... Garanto que as discussões serão boas.
Carlos Roberto | em 08/12/2005 | #
Legal o artigo, só vou completar com uma coisa: mesmo que vc tenha 150% de certeza sobre quem irá ler seu código também conhece seu idioma (aqui, português), escreva seus comentários em inglês.
Em outras palavras: quer comentar, faça em inglês, por favor. Linguagens de programação são em inglês (vide palavras reservadas como for, def, float...) e fazendo comentários em inglês qualquer programador de qualquer lugar do mundo poderá dar manutenção no código.
Já tive o desprazer de dar manutenção em código onde os comentários estavam escritos em Catalão :P
e posso dizer que mal conheço espanhol, quanto mais o dialeto citado. Resutado: ignorei os comentários e achar o bug levou quase dois meses.
Wanderley Caloni | website | e-mail | em 17/01/2007 | #
Isso, a meu ver, vai depender do escopo do seu código. Não faz muito sentido escrever comentários em inglês em uma equipe de desenvolvimento de software nacional. Claro, quem sabe um dia o código vai ser mantido por pessoas que não falam português. E quem sabe um dia você não é chamado pra trabalhar em uma equipe de Moscou.
Quando eu publico artigos no Code Project, reviso meu código e traduzo os comentário, o que acaba sendo útil já que a revisão é saudável de vez em quando.
Claudio Torcato | website | em 27/11/2007 | #
Na premissa de quem devemos sempre escrever um código o mais simples e legível possível, usando nomes adequados para funções e variáveis (deixando a refatoração por conta de performance para depois dos testes de performance - que muitas vezes deixa o código ilegível), os comentários são importantes em trechos de código em que não é possível deixá-lo claro somente por meio do código em si.
Sou a favor da refatoração quando fazemos uma revisita ao código e rapidamente podemos ver que não entendemos o que o mesmo vai fazer. Um comentário inicial numa função deveria ser suficiente em boa parte dos casos para descrever a regra de negócio ali inserida. O código é a consequencia do que ali está escrito.
As idéias que sigo estão baseadas na prática de refatoração.
Luanildo Silva | website | e-mail | em 03/05/2008 | #
Realmente os comentarios ajudam na leitura do codigo, muitas vezes é como se fosse a tradução dos codigos.