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

49

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.

Rachel
fonte
11
Eu não tinha certeza se esses blocos de comentário era de preferência pessoal ou recomendados padrões
Rachel
11
Eu acho que sim também.
Ryan Hayes
30
Eu acho que esse é exatamente o tipo de pergunta que pertence aqui. Há uma boa chance de que isso seja encerrado no stackoverflow como sendo subjetivo.
Paddyslacker 22/09/10
Use os blocos <resumo> se desejar gerar documentação. Isso faria sentido se você estiver criando uma API para outras pessoas usarem. Fazer isso para todos os métodos é um exagero e diminui sua flexibilidade.
Macneil

Respostas:

91

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

Ryan Hayes
fonte
22
+1 Absolutamente usá-los. Você ficaria surpreso com o quão útil é tê-los se você reutilizar seus componentes e tiver toda a excelente documentação disponível no intellisense.
Walter Walter
4
Além disso, se você estiver usando o Visual Studio e iniciar uma linha com /// antes de uma declaração de classe, método ou campo, o VS gerará a estrutura de documentação XML para você - você só precisa preenchê-la. Concordo que isso exige muito espaço na tela, mas é um compromisso digno, eu diria. Além disso, o F # tem algum suporte melhor para ele (por exemplo, você não precisa usar <resumo> e </ resumo> porque eles são "assumidos").
ShdNx 21/09/10
7
Como essa resposta já é a melhor opção, acrescentarei meu comentário: quando descobri que o resumo é usado para o intellisense e meus projetos cresceram para o tamanho atual, fiquei muito feliz por ter encontrado esse recurso. Lembrar para que servem meus métodos e classes estava se tornando um grande desafio, e documentar o código por esse mecanismo simplificou bastante as coisas, permitindo que eu me concentrasse no novo código e na capacidade de recuperação em vez de tentar lembrar o que foi feito meses atrás.
JYelton
3
Apenas uma coisa a acrescentar, esses comentários não são compilados na dll, você precisa entregar o arquivo xml associado à sua dll.
Benjol 9/03/11
Eles são úteis, mas tornam a classe atual muito ilegível. Eu gostaria que houvesse outra maneira que não atrapalhasse o código.
Jeroen van Langen
17

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!

Tom Morgan
fonte
11
O link para o blog parece estar morto (última postagem 5 anos atrás, com html quebrado por toda a página), e a localização do projeto mudou. Você tem um link atualizado para Sandcastle?
12

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

    }
azheglov
fonte
11
Embora eu concorde que o código deva se auto-documentar o mais rápido possível, sugiro usar esses tipos de comentários sempre que possível (e com mais frequência do que os comentários // genéricos). Os comentários /// XML foram projetados para funcionar com o IntelliSense, o que pode facilitar o desenvolvimento meses depois, quando você tenta implementar alguma biblioteca que você construiu e não se lembra bem como ela funciona por mais tempo.
Matt DiTrolio
2
E acho que não apenas do ponto de vista do Intellisense, também do ponto de vista da geração automática de documentação, os comentários xml são úteis. Mas, como em todos os comentários, isso só faz sentido se os comentários em si forem úteis e estão adicionando ao código auto-documentado.
precisa saber é o seguinte
5
Concordo que, ao escrever classes públicas de uma API ou estrutura, o padrão de codificação deve exigir que você coloque comentários no código, para que o IntelliSense e as ferramentas de documentação possam se conectar. Mas isso não é tudo código. Além dessa preocupação, a abordagem que estou defendendo aqui é que, quando você tenta tornar seu código mais limpo e claro, concentre-se no próprio código, não no comentário que descreve o código.
azheglov
3
@ JYelton: seu comentário deturpa minha resposta. Eu impliquei nomes mais descritivos, mas não necessariamente muito mais detalhados, certamente não um identificador de 60 caracteres para uma função pública freqüentemente chamada. Além disso, você tem o que parece ser uma função altamente especializada, mas é necessário um tipo de dados muito geral (XmlDocument) - esse é um cheiro de código. Em seguida, seu identificador de 60 caracteres descreve "como" e não "o que" - de um método público. Esse é outro cheiro. A mensagem principal é: pense primeiro no código, não no comentário.
azheglov
2
@ JYelton O problema com o nome do método não é descritivo, mas descreve pelo menos duas operações separadas e, portanto, deve ser refatorado em pelo menos dois métodos independentes.
Neal
4

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.

John MacIntyre
fonte
11
Nomear é uma coisa, mas listar restrições em parâmetros ou potencialmente geradas exceções ainda é valioso.
Adam Lear
Sim, eu admito que você tem razão, mas na maioria das vezes as restrições dos parâmetros são óbvias, não são?
John MacIntyre
Não tenho certeza se concordo com John. Com essa lógica, nenhum dos métodos da estrutura .net deve obter ajuda do Intellisense.
precisa saber é o seguinte
11
@vaibhav - Eu disse: "Eu recomendaria usá-los em quaisquer classes públicas, métodos e propriedades em uma API, biblioteca, etc ..." ... que cobririam o que você está falando, não é?
precisa
11
@ John - estranho, eu poderia jurar que li outra coisa quando escrevi esse comentário. Porque o seu segundo parágrafo é exatamente o que eu disse em outro lugar neste tópico. Então, eu devo ter pedras na minha cabeça para escrever esse comentário. Sim, eu concordo com isso.
precisa saber é o seguinte
2

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.

Ninguém
fonte
1

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.

Preets
fonte
Comentários obsoletos podem ser considerados um cheiro de código, ainda mais no nível de resumo. Se outros desenvolvedores estão alterando as funções e não atualizando o resumo do que estão fazendo, pode-se argumentar que não estão documentando seu trabalho corretamente.
rjzii
1

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.

Abe Miessler
fonte
1

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

Sreekumar P
fonte
0

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.

Richard
fonte
0

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

Todd Williamson
fonte
0

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

MetalMikester
fonte