ti-enxame.com

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

Alguém disse uma vez que deveríamos prefixar todos os nossos métodos com o /// <summary> blocos de comentários (C #), mas não explicaram 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 normalmente uso // comenta o tempo todo, é apenas o /// <summary> blocos que eu estava pensando.

49
Rachel

se-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. geradas são exibidas no intellisense quando você ou outra pessoa está se preparando para chamar seu método. Eles podem essencialmente ver toda a documentação do seu método ou classe sem precisar ir ao arquivo para descobrir o que ele faz (ou tentar apenas ler a assinatura do método e esperar o melhor).

91
Ryan Hayes

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

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

No último local em que trabalhei, recriamos 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 seja facilmente compartilhado.

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

17
Tom Morgan

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 ) {

    }
12
azheglov

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ê pode cortá-lo, mantê-lo ou excluí-lo.

4
John MacIntyre

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 o que e o por que da coisa que você está resumindo.

Descrever 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.

2
Nobody

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 uma vez que percebo alguns comentários de mau comportamento, tenho tendência a perder a fé em todos os comentários desse projeto - você nunca sabe ao certo em quais confiar.

1
Preets

Esquecer de fazer algo não a torna uma má idéia. Esquecer de atualizar qualquer documentação é. Eu os achei muito úteis 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 ter que 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.

1
Abe Miessler

"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).

1
Sreekumar P

Eu uso o equivalente em VB (já que eles não me permitem usar C # - aparentemente é muito difícil ... sem comentários)) Acho muito conveniente. Na maioria das vezes, espero até o procedimento ou função é 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).

0
MetalMikester

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 ao Assembly, sem seu projeto, mostrará mais detalhes no intellisense.

Mas para as partes internas do projeto atual, elas apenas atrapalham.

0
Richard

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 for anotado em algum lugar, o código é o local em que ele provavelmente permanecerá atualizado (mais provavelmente do que algum documento do Word flutuando).

0
Todd Williamson