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:

Jerry disse...

Menos verborragia, com certeza...

E passando mensagens e não chamando funções.

Além disso, qual a verdadeira diferença entre elemento1 e e1?

Objetos com nome do negócio, nomes pequenos e significativos para facilitar a leitura e não dizer o óbvio:

e1.podeFazer(e2);

É suficiente!

Peter disse...

Acho que isso depende. Em alguns casos, onde a declaração da referência está próxima, o código é curto e a referência não será utilizada novamente muitas vezes, realmente pode não ser um grande problema ter o nome encurtado. É o caso do meu exemplo, mas bem, é um exemplo. Poderia ser algo mais complexo e eu pretendia fazer um exemplo genérico.
Acho importante ter nomes que digam alguma coisa sobre a referência que você está criando. Repare que você pode utilizar em um trecho de código distante da declaração da referência, quando não saberá mais, sem consultar, para que ela foi criada. Também poderá se sentir tentado a "reaproveitar" a referência para apontar para outro objeto, para fazer outra coisa, já que o nome é genérico. Assim o código ficará confuso, com a mesma referência servindo a mais de um propósito. Em via de regra, acho preferível escrever "elemento1" (claro, considerando que "elemento" seja um nome com algum significado pro código e não um nome genérico como parece ser por força do exemplo).

zimbrao disse...

Penso exatamente assim, Peter!
Nenhum comentário é mais eficiente do que um código legível, e um código legível dispensa comentários!

A propósito, parabéns pela iniciativa de criar um blog! Com toda certeza, dá muito trabalho...

Sucesso com seu blog!!

Luiz Eduardo Guida Valmont disse...

Concordo com menos comentários e um código o mais próximo de ser auto-exeplicativo o possível.

Meus R$0,02... quando defino métodos/funções, por exemplo, tento, se possível tornar sua chamada "legível", algo próximo do que seria falado. Exemplo: preciso de um método para acrescentar um valor em uma string; "acrescentar valor X na string S" gera "acrescentarValor( X, S )". Em C, por exemplo, há funções como sprintf; seria algo como "imprima em S o valor X". Mas normalmente costumo dizer "imprima o valor X em S"; nesse sentido, no que diz respeito à legibilidade, "acrescentarValor( X, S );" é mais legível que "sprintf( msg, "...", ... );". Eu acho. Ponto: a ordem dos parâmetros é fundamental para legibilidade do código.

Postar um comentário

 
addthis_config = { data_ga_tracker: pageTracker }