Documentação
Embora o exemplo postado chame oficialmente de comentário de documentação e tenha uma semântica de comentário mesmo, ou seja, o compilador em sua operação normal o ignora completamente, considere-o como documentação e não como comentário.
Documentação é importante? Claro. A não ser que esteja fazendo um protótipo, um script muito simples, ou algo descartável, documentação é fundamental.
Acredito que a única "polêmica" sobre o assunto é se membros privados de uma classe devem ser documentados também. Alguns vão dizer que sim, outros acharão que um comentário simples é suficiente, e alguns dirão que não precisa documentar o detalhe de implementação, que só a API pública deve ser documentada.
É provável que você tenha colocado o trecho de documentação só para ilustrar, mas para deixar claro, o que não pode é deixar da forma que está aí. Muitas pessoas deixam só o esqueleto da documentação sem conteúdo.
Eu acho o recurso da documentação com ///
muito bom. Gostaria que a formatação fosse mais simples, provavelmente JSON, Markdown ou algo assim. Mas foi desenvolvida no momento que a Microsoft estava amando XML. Ainda assim é útil.
Tags
Você tem tags que ajudam bastante identificar o que a classe faz e como usá-la. Lembre-se que a documentação deve ajudar quem vai usar a classe. Que será você no futuro ou outro programador. A documentação, em parte carrega um pouco da especificação. De fato é possível até linkar para documentos extras para notas dessas especificação.
As tags possuem alguma semântica. O próprio compilador sabe interpretar essas tags e usam esses comentários no Visual Studio para informar melhor o programador no Intellisense, Object Browser, etc.
Você pode até mesmo criar tags personalizadas. Existem alguns softwares sofisticados para gerar saídas bem formatadas. Talvez o mais moderno e ativo atualmente seja o SandCastle (tem outros).
Embora possa colocar em qualquer lugar, acho que falta, por exemplo, uma tag <deprecated>
. Talvez porque exista um atributo para identificar isso no código. Mas na tag você poderia explicar e indicar alternativa. Daria mais semântica que colocar em <remarks>
.
Também não sofra da síndrome do canivete suíço. Ninguém é obrigado a usar todas as tags. Depende do que você está fazendo, um simples <summary>
é suficiente. Em geral documentar os parâmetros e retorno também é necessário. Indicar exceções que o método pode gerar é importante.
Arquivo externo
É possível incluir a documentação vinda de um arquivo externo. Não acho esse recurso particularmente útil. O ideal é ter a documentação mais próximo possível do que ela está documentando. Se for para colocar em outro arquivo, então não precisa ter uma ligação. Talvez para facilitar o acesso ao arquivo, sei lá.
Mas também não é o fim do mundo usar um arquivo separado. Documentação costuma ser bastante estável. Ou seja, a não ser por melhorias no conteúdo você raramente mexe nela. Se está documentado só a parte pública da classe tem que ser assim, afinal depois que você criou uma classe, um método, você não pode sair mudando-o muito, sob risco de quebrar programas que estão usando-os. Se o contrato não muda, a documentação não muda.
Diferença entre documentação e comentário
Documentação documenta o contrato, não a implementação, não o código propriamente dito. Por isso é bom não chamá-la de comentário. Documentação diz o que a classe e o método faz em linhas gerais, ajuda eles serem usados.
Cabeçalho com autoria
Quando você olha a lista de tags que a Microsoft criou para você usar, você encontra autor ou data de criação? Não.
Tem uma boa razão para isso. Este tipo de informação deve estar no controle de versão. Isso será armazenado no SVN, no Git, no Mercurial, no TFS, etc. Use a ferramenta certa para controlar autoria. Nunca use cabeçalho de métodos para isso. Com o tempo você perceberá que é contraprodutivo e/ou que ninguém respeita isso.
Tem recomendações que perduram mais do que deveriam. O que vou dizer a seguir vale para muitas recomendações sobre estilo de codificação. As pessoas precisam saber o porquê de uma recomendação. Quando as pessoas aprendem só a recomendação elas não sabem quando parar de usar.
- Nos anos 60 tinha motivo para usar isso, o código era simples, não havia ferramentas melhores.
- Nos anos 70 era algo bem útil ainda.
- Nos anos 80 era aceitável como uma forma simples de documentar.
- Nos anos 90 era tolerável, nem todos sabiam como fazer melhor, nem sempre havia recursos melhores disponíveis.
- Neste século é inacreditável que ainda exista isso. E existe.
Exemplo real de uso errado
Trabalhei em um grande fornecedor se sistema ERP e este sempre foi o método de "documentar" o sistema. Tive acesso aos fontes mais recentes e continua assim. E pior, continua uma bagunça.
Raramente alguém atualiza o cabeçalho para indicar as alterações (apesar que eu não sei se isso é bom ou ruim neste caso), quando atualizam, é comum não colocar como alteração. Vi várias funções que eu sei que foram totalamnete desenvolvidas por mim com nome de outra pessoa porque ela trocou uma vírgula na função. Tudo bem, isso sempre foi a cultura lá. Mas já mostra que o cabeçalho de fato não serve para muita coisa. É pura burocracia sem sentido.
Imagine o que vale saber quem criou uma função 20 anos depois que ela saiu da empresa. A data de criação é tão relevante? Ou o histórico completo é que é? Versão? Versão do que? Do método? Quem controla isso? Versão da aplicação? Vai sair mudando em todos os lugares cada vez que muda a versão da aplicação?
Como saber o histórico real, que linhas foram alteradas, a sequência precisa, sem esquecer de nada? Só um software de controle de versão consegue isso. Nem perca tempo com este tipo de informação em código. E não falo só do autor, qualquer coisa que possa se tornar irrelevante ou que não seja fácil manter correto.
No código não importa "quem e quando". Estas informações devem estar no controle de versão.
Exceção
Existe um caso que o cabeçalho é admissível. Colocar informações legais, como copyright por exemplo. Existem casos que isso é útil ou até obrigatório de acordo com a licença do código. Normalmente é mais no cabeçalho do arquivo e não da classe ou método.
Comentando código
É aqui onde há mais discordância da medida certa.
Legado
Nos primórdios da programação a regra do "comente todo seu código" era muito importante. Muitos não sabem que as linguagens não tinham estruturas adequadas para expressar o código, não tinham funções, as variáveis tinham que ser curtas (2 caracteres!) e você tinha que buscar performance acima de tudo. Os comentários eram fundamentais para entender um programa. Existiam e ainda existem linguagens que nem variáveis têm. Em uma linguagem Assembly comentários extensivos continuam importantes, afinal estamos falando de uma linguagem quase ilegível.
Mas isso tudo mudou nas linguagens de alto nível. Hoje comentários quase não são necessários. Bom, C é uma linguagem que ainda precisa um pouco, mas mais pelo estilo comum que os programadores C costumam programar do que por limitação atual da linguagem. C costuma ser usado como um Assembly portável.
Exageros
Há quem ainda ache que comentários devem ser extensivos. Já pedi demissão de emprego que me obrigava fazer algo assim:
//Este método vai inicializar os componentes
InicializaComponentes();
Juro! Mas quem pensa sobre o assunto, hoje reconhece que comentários em código devem ser bem limitados. Comentários em código são mais difíceis de manter. Você está comentado o detalhe de implementação, isso pode mudar a qualquer momento.
Problemas
Convenhamos, ninguém gosta de comentar.
Há quem ache que um comentário desatualizado é melhor que nada, há quem ache que isso é pior que nada. Eu digo que varia de caso para caso. Não há como saber se vai ser pior ou melhor. Eu acho que o risco é menor não comentado algo.
O mais importante é que o código seja expressivo. Se ele foi bem pensado, e bem construído, o comentário se torna desnecessário. O código, e não o comentário, deve dizer como fazer.
O que deve conter nos comentários?
Comentários que dão referência de onde encontrar mais informações para entender a decisão, o algoritmo escolhido, ou que explique a fórmula adotada, são sempre muito apropriados. Em alguns casos essa referência pode estar na documentação, mas nem sempre.
- Essa referência é detalhe de implementação? É comentário.
- Faz parte do contrato? É útil para o consumidor da classe/método? É documentação.
Cuidado para não abusar disto. Muitas destas referências talvez caibam mais no controle de versão do que no código. Imagine colocar um comentário para cada ticket de bug que você resolveu. Isso vai na mensagem de commit do controle de versão.
Já um link para a resposta no SOpt onde você ganhou o algoritmo pronto é até questão de ética :D
Para tudo existe exceção. Indicar um ticket para mostrar um bug que deve ser evitado em futuras alterações é uma boa. Você está explicando o porque de ter adotado um caminho que não parece ser o melhor à primeira vista.
Comentário semântico
Alguns comentários podem ter semântica. Ex.: //TODO: xxx, //TOFIX: yyy, //HACK: zzz. Existem ferramentas que te alertam para alguns deles. Isso ajuda você não esquecer que algo ainda precisa de trabalho. O problema é que as pessoas os ignoram. Quando esses comentários duram muito tempo eles perdem a vantagem.
Melhorando o código antes de comentar
Não vou detalhar aqui o que já foi dito em outras respostas, mas mantenha nomes significativos para tudo, métodos curtos que façam apenas uma tarefa, mantendo o mesmo nível de abstração dos demais.
Resumo
Existem algumas dicas para definir quando comentar:
- diga porque o código está ali e não o que ele faz;
- não use
} //if (cond)
, se isso é necessário, seu if
está muito grande (ou while
, for
, etc.);
- evite deixar código commented out, código que não deve ser executado mais (na versão final antes do commit, no momento que está mexendo, ok);
- seja muito sucinto;
- se o código precisa de comentário, ele pode estar complexo demais (a não ser que o domínio seja complexo);
- comentários são bons para explicar código que ficou "sujo" por necessidade de otimização;
- evite surpresas que o programador pode ter, explicando o que está por vir (algo que pode ser um WTF), alerte para e amplifique consequências ou workarrounds usados;
- evite redundância, mas use quando for realmente útil, pense antes de escrever;
- explique a intenção do código quando não é óbvia e não é possível mostrar isso em código de forma simples;
- os comentários devem ser simples, não os enfeite;
- se a informação do comentário é muito grande, talvez ele deva estar em uma nota externa;
Existem pessoas que preferem ter algumas tags definidas para dar semântica ao comentário (HACK, REF, TOFIX, SECURITY:, etc). E quando nenhuma tag parece ser adequada, é sinal que o comentário não deveria estar ali.
Não se esqueça que qualquer regra pode e deve ser quebrada para obter um resultado melhor. A experiência qualitativa ajuda decidir isso. Não esqueça também que algumas pessoas discordarão de boa parte destas regras.
Referências
Exitem estudos sérios sobre o assunto. O difícil é achar :)
Alguns livros que podem ajudar ou atrapalhar você (lembra do emprego que pedi demissão? Meu chefe era fã desses livros):
- Code Complete - Steve McConnell
- The Pragmatic Programmer - Andy Hunt and Dave Thomas
- Clean Code: A Handbook of Agile Software Craftsmanship - Robert "Uncle Bob" Martin
Por exemplo, um destes livros, que é quase uma unanimidade entre programadores, é opinativo, confuso, impreciso, e especialmente contraditório, ou seja, parece horóscopo. Ele fala algo ótimo para uma linguagem e péssimo para outras. Mas não diz quando deve usar. Aí as pessoas generalizam. Não explica porque usar várias recomendações. Mesmo quando explica, o programador inexperiente não entende quando o argumento dele é ruim. Também não estou dizendo que o livro não serve para nada.
Coloquei no GitHub para referência futura.