Você comenta seu código?

segunda-feira, 7 de setembro de 2009

Para quem não sabe, sou monitor honorário da disciplina "Computação II" no Departamento de Ciência da Computação da UFRJ (http://www.dcc.ufrj.br/~comp2/professor.html).
Como monitor honorário eu ajudo os outros monitores nas tarefas que me agradam. ;-) Isso significa dar aulas de apoio e tirar dúvidas, principalmente.
Na última semana um aluno perguntou sobre a importância de comentar o código dos exercícios a serem corrigidos. Adaptei a resposta para a pergunta "É importante comentar?".
É MUITO importante que seu código seja compreensível, não só por você mesmo (agora ou no futuro), por pessoas que trabalham com você ou trabalharão num projeto em que você desenvolveu um dia.
Como regra, eu adoto a política de tentar fazer um código tão claro que dispense comentários. Só quando isto não é possível por uma idiossincrasia da vida que eu comento e tento ser o mais explicativo possível.

“There are two ways of constructing a software design; one way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.” Sir Charles Antony Richard Hoare

Reparem, por exemplo, neste trecho fictício:
if ((e1.comparaMaior(e2) || e1.vazio()) && (e2 != null)) {
    fazerAlgo();
}

em contraste com:
if (elemento1AtendeRestricaoComparandoElemento2(elemento1, elemento2)) {
    fazerAlgo();
}

boolean elemento1AtendeRestricaoComparandoElemento2(Elemento elemento1, Elemento elemento2) {
    return (elemento1.comparaMaior(elemento2) || elemento1.vazio()) && (elemento2 != null);
}


Notem que fica claro o que está sendo testado no if e fica clara também a intenção daquela comparação enorme graças ao nome método implementado em seguida. Não é necessário o comentário. Assim, evita-se, entre outras coisas, que o código seja atualizado, e o comentário esquecido, ficando desatualizado e informando uma condição diferente da que acontece, causando muitos transtornos.
Além disso, se a intenção é entender a finalidade do código, muitas vezes entender a comparação é desncessário.

Usar nomes de variáveis que signifiquem alguma coisa também é outra boa prática. Todas as boas IDEs completam os nomes quando digitamos os primeiros caracteres e pressionamos ctrl+space.
Notem que não poupei letras no nome do método. O importante é deixar claro e organizado.

Vale notar também que este código é agora mais testável, já que é possível testar apenas a comparação. ;-)

Uma situação válida para a utilização de comentários é quando entendemos algum código um pouco complicado, que demanda algum raciocínio de como o código funciona para entendermos seu objetivo. Neste caso, vale comentar o objetivo se não for possível (por restrições quaisquer) refatorá-lo para torná-lo adequado ao entendimento.

O Javadoc também é bem interessante, mas nele deve constar apenas "o que" o método faz (objetivo) e não "como" o método faz (lógica). Assim, a documentação se torna suscinta, simples e direta, atendendo aos objetivos de quem a lê. Quem quiser entender como irá ler o código e o deve encontrar devidamente organizado.

E vocês? O que comentam? Como comentam?

Abraço a todos!

Bookmark and Share

4 comentários:

Postar um comentário

 
addthis_config = { data_ga_tracker: pageTracker }