Skip to main content
2 de 9
adicionou 390 caracteres ao conteúdo
Maniero
  • 484,5mil
  • 94
  • 1,3mil
  • 2,2mil

A maioria do que eu poderia dizer já foi dito nas respostas e em minha resposta nessa pergunta. Leia também as outras perguntas, de uma maneira geral concordo com elas. Não acho que o que foi exposto na pergunta citada sirva só para C#. Alguns pontos sim, mas quase todos eram universais.

Para consolidar e mostrar porque se prega o uso de comentários vou postar algo extra.

Comentários não são bons porque eles ferem o DRY. Eles são difíceis de manter sincronizados. Comentário devem dizer porque algo foi feito e nunca o que foram feitos.

#Documentação

Não confunda comentários com documentação. Documentar as classes e métodos mesmo usando o mecanismo de comentários não devem ser interpretados como comentários. Esta documentação é mais fácil manter sincronizada com o código porque ela só documenta o contrato. E contratos não devem ser mudados. Mas se o contrato for mudado assim mesmo, certamente haverá muitos testes e precisará ser comunicado para todos os usuários. Certamente a mudança na documentação não será esquecida. E se for, sua equipe está toda lascada mesmo, entrega pra deus :)

Documentação deve fornecer informações relevantes. Leia a documentação de APIs conhecidas que têm fama de serem bem documentadas para ver o que é relevante. Colocar o óbvio não ajuda nada. Um comentário bobo só para dizer que documentou não serve para muita coisa. Deve haver explicação das implicações do uso daquela classe ou método. O que pode dar errado, quando usar e não usar. Porque aquilo existe, especialmente se parecer que não deveria existir. Documentar significa informar todos os aspectos daquilo, todos os dados importantes para o contrato, como parâmetros, retorno, exceções possíveis.

Para aprender só não vale olhar a documentação do PHP que é muito ruim :) Mentira, ela é melhor do que a maioria das documentações que as pessoas fazem. Ela só não é tão boa quanto algumas outras muito boas, que são exemplos de documentação bem feita. Embora nenhuma seja nota 10 também. Documentar bem é difícil.

Mas também tem que ver o custo de documentar isto. Nem sempre vale o esforço. Isto será muito grande? É muito complicado acompanhar sem documentação? Será que não dá para simplificar a arquitetura para evitar ter que documentar tanto? Muitas vezes não precisa de tudo o que foi feito. Dá para tornar privadas algumas partes e tirar da API? Será usado por muita gente? Por muito tempo?

Se linguagens de programação extramente populares não fazem documentações nota 10 em suas APIs, porque você deveria fazer isto com seus sistema que será usado por uns poucos programadores? Pense nisto. E se não for para documentar razoavelmente bem, melhor nem documentar.

#Códigos expressivos

Comentários de verdade só são necessários quando o código está mal escrito.

Comentários eram incentivados nos anos 50 e 60 quando as linguagens eram limitadas. Era comum variáveis só poderem ter 2 caracteres, funções nem existiam, ou também não podiam ter nomes expressivos. A memória era tão escassa que qualquer economia contava. O mesmo vale para ciclos de processamento. O importante era produzir código eficiente, até porque os compiladores eram bem ruins para otimizar. Legibilidade era secundária, tornando o comentário essencial. Na verdade onde mais se usava comentário era em Assembly - muito usado na época - que tem expressividade quase zero.

Isto foi ensinado para os recém-chegados na profissão. E eles se tornaram professores. Todos escreveram livros. E o conhecimento foi sendo passado para gerações. Mas a tecnologia mudou, as linguagens, os compiladores mais modernos e os recursos mais folgados permitiram preferir códigos legíveis e dispensar quase por completo o uso de comentários. Só que muita gente não percebeu isto. E continuam repetindo o mantra.

Em alguma resposta ou comentário meu eu já critiquei o uso de comentários redundantes, como os usados no seu exemplo. Eu já pedi demissão porque eu era obrigado fazer isto:

//Este método inicializa os componentes
InicalizaComponentes();

Note que é uma chamada, que é ainda pior documentar o uso. Se fosse na definição do método e explicasse porque ele é necessário, como ele age no sistema, aí tudo bem. Mas isto não só não era necessário, como não era feito por ninguém.

#HTML

Mesmo HTML que não é muito expressivo, mas por outro lado também não gera tanta confusão, não é muito necessário.

Se você organizar (com espaçamento vertical e horizontal) o código de forma à facilitar a fluência da leitura e se colocar nomes expressivos em id, class, name e outros atributos, eventualmente até colocar onde não são necessários naquele momento, também não precisa de comentário.

Eu vejo mais motivo para comentar código CSS. Ali tá cheio de gambiarras para funcionar em todos os navegadores. Tem que explicar porque está usando aquilo. Não tem como fazer código expressivo o suficiente para indicar porque aquela maluquice está ali. E nem precisa ser muito maluco para precisar de comentário.

Quase ninguém comenta CSS e quando comenta, em geral não é bem feito.

Maniero
  • 484,5mil
  • 94
  • 1,3mil
  • 2,2mil