Por que os blocos de /// comment são importantes?

Alguém disse uma vez que deveríamos prefixar todos os nossos métodos com os /// <summary>blocos de comentários (C #), mas não explicou o porquê.

Comecei a usá-los e descobri que eles me incomodavam um pouco, então parei de usá-los, exceto para bibliotecas e métodos estáticos. Eles são volumosos e eu sempre esqueço de atualizá-los.

Existe algum bom motivo para usar /// <summary>blocos de comentários no seu código?

Eu costumo usar //comentários o tempo todo, são apenas os /// <summary>blocos que eu estava pensando.

Use-os o máximo possível.

Sim, esses são comentários especiais que se tornam a documentação para o método. O conteúdo de <summary>, as tags de parâmetro etc. gerados são exibidos no intellisense quando você ou outra pessoa está se preparando para chamar seu método. Essencialmente, eles podem ver toda a documentação do seu método ou classe sem precisar ir ao próprio arquivo para descobrir o que ele faz (ou tentar apenas ler a assinatura do método e esperar o melhor).

Sim, use-os absolutamente para qualquer coisa que você queira manter ou possa ser compartilhado.

Além disso, use-os em conjunto com o Sandcastle e o Sandcastle Help File Builder , que pega a saída XML e a transforma em uma bela documentação no estilo MSDN.

No último local em que trabalhei, reconstruímos a documentação todas as noites e a hospedamos como uma página inicial interna. As iniciais da empresa eram MF, então era MFDN;)

Normalmente, embora eu apenas produza um arquivo .chm, que é facilmente compartilhado.

Você ficaria surpreso com a dependência de documentar tudo quando começar a vê-lo no formato MSDN!

Se o seu padrão de codificação exigir que você use esses comentários (e um padrão de codificação para uma API ou estrutura possa exigir isso), você não terá escolha, precisará usar esses comentários.

Caso contrário, considere seriamente não usar esses comentários. Você pode evitá-los na maioria dos casos, alterando seu código assim:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

para

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

para

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Seus nomes de classe, método e propriedade devem ser evidentes; portanto, se você precisar deles, provavelmente é um cheiro.

No entanto, eu recomendaria usá-los em quaisquer classes públicas, métodos e propriedades em uma API, biblioteca, etc ... No mínimo, eles gerarão os documentos para ajudar qualquer desenvolvedor a usá-lo e impedirão que você tenha escrevê-los.

Mas de qualquer maneira, você o corta, mantém ou exclui.

Se você achar que precisa voltar e editar seus comentários para corresponder ao novo código, pode estar fazendo errado de início. O elemento de resumo deve conter exatamente isso - um resumo - o quê e o porquê da coisa que você está resumindo.

A descrição de como algo funciona nos comentários viola o DRY. Se o seu código não for auto-descritivo o suficiente, talvez você deva voltar e refatorar.

Sim, eu os criei. [ao construir novos sistemas a partir do zero]

Não, nunca me beneficiei deles. [ao trabalhar em sistemas existentes que precisavam de manutenção]

Descobri que os comentários "Resumo" tendem a ficar fora de sincronia com o código. E, quando percebo alguns comentários que se comportam mal, tenho tendência a perder a fé em todos os comentários desse projeto - você nunca sabe ao certo em quais confiar.

Esquecer de fazer algo não a torna uma má idéia. Esquecer de atualizar qualquer documentação é. Eu achei isso muito útil na minha programação e as pessoas que herdam o meu código são gratas por tê-los.

É uma das maneiras mais visíveis de documentar seu código.

É difícil encontrar o código-fonte para ler a documentação embutida ou desenterrar um documento que repasse o que o código faz. Se você pode obter algo útil através da inteligência, as pessoas o amarão.

" Tem que ser usado muito, como eu;) "

Eu costumava brincar com comentários (///). Para uma aula, você pode simplesmente fazer um comentário como este

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Mas, para um método, você pode adicionar mais, fornecendo descrição para parâmetros e tipos de retorno.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Você pode usar um atalho para criar este comentário (///+Tab).

usá-los, exceto para bibliotecas

Esse é o momento em que são úteis. Com a geração da documentação XML ativada e uma referência à montagem, sem seu projeto, mostrará mais detalhes no intellisense.

Mas para os internos do projeto atual, eles apenas atrapalham.

Eu os uso, mas como algumas pessoas disseram não universalmente. Para métodos pequenos, eles podem ser facilmente maiores que o código que estão explicando. Eles são mais úteis para gerar documentação que pode ser fornecida a pessoas novas no sistema, para que tenham algo a que se referir enquanto aprendem. Mesmo assim, como programadores, geralmente podemos descobrir o que é algum código, pois é bom ter os comentários para nos guiar e agir como uma muleta. Se tiver que ser anotado em algum lugar, no código é o local mais provável de se manter atualizado (mais provável do que algum documento do Word flutuando).

Eu uso o equivalente no VB (já que eles não me permitem usar C # - aparentemente é muito difícil ... sem comentários.) Acho-os muito convenientes. Na maioria das vezes, espero até que o procedimento ou função seja praticamente concluído antes de inseri-los, apenas para evitar a necessidade de alterar os comentários - ou deixá-los "fora de sincronia".

Eu não necessariamente escrevo um romance - apenas o básico, a descrição do parâmetro e algumas observações (geralmente quando há algo "fora do comum" acontecendo lá - solução alternativa ou outra porcaria que eu preferiria não ter, mas tenho nenhuma escolha "por enquanto".) (Sim, eu sei, que "por enquanto" pode durar anos.)

Estou severamente irritado com código não comentado. Um consultor escreveu a versão inicial de um de nossos componentes e não comentou nada, e sua escolha de nomes deixa a desejar aqui e ali. Ele se foi há mais de um ano e ainda estamos resolvendo as coisas dele (além de trabalhar em nossas próprias coisas).