Se apimentar seu código com muitos comentários é bom, então ter zilhões de comentários em seu código devem ser ótimo, certo? Não é bem assim. O excesso é uma forma bons comentários se tornam ruins:
'************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) 222-2255 ' SSN: 111-22-3333 ' Eye Color: Green ' Maiden Name: None ' Blood Type: AB- ' Mother's Maiden Name: None ' Favorite Car: Pontiac Aztek ' Personalized License Plate: "Tek-ie" '*************************************************
Constantemente me deparo com comentários de desenvolvedores que parecem não entender que o código já nos diz como funciona; precisamos que os comentários nos digam por que funciona. Os comentários de código são tão amplamente incompreendidos e abusados que o senhor pode acabar se perguntando se vale a pena usá-los. Cuidado com o que o senhor deseja. Aqui está um código com sem nenhum comentário:
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );
O senhor tem alguma ideia do que esse trecho de código faz? Ele é perfeitamente legível, mas o o que diabos ele faz?
Vamos adicionar um comentário.
// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );
Deve ser isso que eu estava querendo dizer, certo? Algum tipo de compromisso agradável e intermediário entre os dois extremos polares de nenhum comentário e poemas épicos cuidadosamente formatados a cada duas linhas de código?
Não exatamente. Em vez de adicionar um comentário, eu refatoraria para isso:
private double SquareRootApproximation(n) {
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
return r;
}
System.out.println( "r = " + SquareRootApproximation(r) );
Não adicionei um único comentário e, ainda assim, essa parte misteriosa do código agora é perfeitamente compreensível.
Embora os comentários não sejam inerentemente bons ou ruins, eles são frequentemente usados como muleta. O senhor deve sempre escrever seu código como se os comentários não existissem. Este forças o senhor a escrever seu código da maneira mais simples, clara e autodocumentada que puder imaginar.
Quando tiver reescrito, refatorado e rearquitetado seu código uma dúzia de vezes para facilitar a leitura e o entendimento de seus colegas desenvolvedores, quando não conseguir imaginar nenhuma maneira concebível de alterar seu código para torná-lo mais simples e óbvio, então, e só então, o senhor deve se sentir compelido a adicionar um comentário explicando o que seu código faz.
Como o senhor Steve apontaessa é uma diferença fundamental entre desenvolvedores juniores e sênior:
Antigamente, ver muito código de uma só vez excedia francamente meu limite de complexidade e, quando eu tinha que trabalhar com ele, normalmente tentava reescrevê-lo ou, pelo menos, comentá-lo bastante. Hoje em dia, no entanto, eu simplesmente o examino sem reclamar (muito). Quando tenho um objetivo específico em mente e um código complicado para escrever, gasto meu tempo fazendo-o acontecer em vez de ficar contando histórias sobre ele [in comments].
Os desenvolvedores juniores confiam nos comentários para contar a história, quando deveriam confiar no código para contar a história. Os comentários são apartes narrativos, importantes à sua maneira, mas que não devem substituir o enredo, a caracterização e o cenário.
Talvez esse seja o pequeno segredo sujo dos comentários de código: para escrever bons comentários, o senhor precisa ser um bom escritor. Os comentários não são códigos destinados ao compilador, são palavras destinadas a comunicar ideias a outros seres humanos. Embora eu goste (principalmente) dos meus colegas programadores, não posso dizer que a comunicação eficaz com outros seres humanos seja exatamente o nosso ponto forte. Já vi e-mails de três parágrafos de desenvolvedores das minhas equipes que praticamente derreteram meu cérebro. Esses são as pessoas em quem confiamos para escrever comentários claros e compreensíveis em nosso código? Acho que talvez seja melhor para alguns de nós nos atermos aos nossos pontos fortes, ou seja, escrever para o compilador, da forma mais clara possível, e usar os comentários apenas como método de último recurso.
Escrever comentários bons e significativos é difícil. É uma arte tão grande quanto escrever o código em si, talvez até mais. Como Sammy Larbi disse em Desculpas comuns usadas para comentar códigosSe o senhor acha que seu código é muito complexo para ser entendido sem comentários, seu código provavelmente é ruim. Reescreva-o até que ele não precise mais de comentários. Se, ao final desse esforço, o senhor ainda achar que os comentários são necessários, então, com certeza, adicione comentários… com cuidado.