Rodrigo Strauss :: Blog
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
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.