A maioria do que eu poderia dizer já foi dito nas respostas aqui e em minha resposta [nessa pergunta][1]. Leia também as outras respostas lá, 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 são universais. Para consolidar e mostrar porque se prega o uso de comentários vou postar algo adicional. Comentários não são bons porque eles ferem o [DRY][2]. Eles são difíceis de manter sincronizados. Comentários devem dizer porque algo foi feito e nunca o que foi feito ali. #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 extremamente 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. Você não percebe que as pessoas tem dificuldades em comentar? Parece um fardo fazer isto. E é algo bem mais fácil e menos trabalhoso que codificar. Talvez, não tenho estudos sobre o assunto, seja porque subconscientemente as pessoas sabem que aquilo não ser para nada. Aí elas deixam de fazer quando o comentário é realmente necessário. O cérebro é muito confuso. Por isto propagandas usam esta falha para associar produtos com sentimentos bons. Por isto a gamificação funciona. Você tem que treinar seu cérebro para aceitar a importância dos comentários necessários e não deixar ele se confundir com a parte sábia dele que diz que comentário devem ser evitados. 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 e CSS Mesmo HTML que não sendo muito expressivo, mas por outro lado também não gera tanta confusão, não é muito necessário. [HTML não é uma linguagem de programação][3]. 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é colocando 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. #Conclusão Uma coisa que eu aprendi é que a pessoa que não consegue programar direito não vai conseguir comentar direito. Por isto muitos comentários não só falam o óbvio mas fazem o oposto, falam coisa que não condizem com a realidade. Ela muitas vezes não entende o que ela está fazendo. Ela até sabe que o resultado está sendo produzindo mas ela não entende a semântica daquilo. E comentário, mesmo os que estamos dizendo que não são bons, servem para dar mais semântica ao que está sendo feito. Se o programador não sabe definir com clareza o que ocorre **de fato** ali, o comentário sairá errado. Eu mesmo depois de mais de 30 anos de experiência tenho dificuldades de entender totalmente o problema que estou lidando quando é um problema novo para mim. Um exemplo de como é fácil entender errado uma coisa pode ser vista em mais uma [excelente resposta do Eric Lippert][4]. Eu não sei como resolver isto a não ser treinar bastante e talvez procurar ajuda profissional específica para ajudar na capacidade cognitiva. [1]: https://pt.stackoverflow.com/q/13890/101 [2]: https://pt.stackoverflow.com/q/120931/101 [3]: https://pt.stackoverflow.com/q/35547/101 [4]: https://stackoverflow.com/a/21694054/221800