Alguém disse uma vez que devemos prefixar todos os nossos métodos com os blocos de comentários /// <summary> (C #), mas não explicou o motivo.
Comecei a usá-los e descobri que eles me incomodavam bastante, então parei de usá-los, exceto por bibliotecas e métodos estáticos. Eles são volumosos e eu estou sempre esquecendo de atualizá-los.
Existe algum bom motivo para usar /// <summary> blocos de comentários em seu código?
Normalmente, uso // de comentários o tempo todo, são apenas os blocos /// <summary> que eu estava pensando.
Use them as much as possible.
Sim, esses são comentários especiais que se tornam a documentação do método. O conteúdo de <summary> , as tags de parâmetro, etc. que são geradas aparecem 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 ter que ir ao próprio arquivo para descobrir o que ele faz (ou tentar apenas ler a assinatura do método e esperar pelo melhor).
Sim, absolutamente use-os para qualquer coisa que queira manter ou que possa ser compartilhada.
Além disso, use-os em conjunto com o Sandcastle e o Criador de arquivos de ajuda do Sandcastle , que pega a saída XML e a transforma em uma documentação bonita no estilo do MSDN.
Último lugar em que trabalhei nós reconstruímos a documentação toda noite e a hospedamos como uma homepage interna. As iniciais da empresa eram MF, então era MFDN;)
Normalmente eu apenas produzo um arquivo .chm, que é facilmente compartilhado por aí.
Você ficaria surpreso em saber como ficou viciado ao documentar tudo assim que começar a vê-lo no formato MSDN!
Se o seu padrão de codificação exige que você use tais comentários (e um padrão de codificação para uma API ou framework pode exigir isso), então você não tem escolha, você tem que usar tais comentários.
Caso contrário, considere seriamente não usar tais comentários. Você pode evitá-los na maioria dos casos, alterando seu código da seguinte forma:
/// <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 ) {
}
Sua turma, método e & a nomenclatura da propriedade deve ser evidente, portanto, se você precisar deles, provavelmente é um cheiro.
No entanto, eu recomendaria usá-los em quaisquer classes, métodos e & públicos propriedades em uma API, biblioteca, etc ... No mínimo, eles irão gerar os documentos para ajudar qualquer desenvolvedor usando o seu, e evitará que você tenha que escrevê-los.
Mas, de qualquer forma, você faz isso, mantém ou exclui.
Se você achar que precisa continuar voltando e editando seus comentários para que correspondam a um novo código, você pode estar cometendo erros em primeiro lugar. O elemento de resumo deve conter exatamente isso - um resumo - o o que e o porquê da coisa que você está resumindo.
Descrever como algo funciona nos comentários viola DRY. Se o seu código não é auto-descritivo o suficiente, talvez você deva voltar e refatorar.
Sim, eu os criei. [ao construir novos sistemas a partir do zero]
Não, eu nunca me beneficiei deles. [ao trabalhar em sistemas existentes que precisavam de manutenção]
Descobri que os comentários de "Resumo" tendem a ficar fora de sincronia com o código. E uma vez que eu noto alguns comentários mal comportados, eu costumo perder a fé em todos os comentários sobre esse projeto - você nunca sabe em quem confiar.
Esquecer de fazer algo não é uma má ideia. Esquecer de atualizar qualquer documentação é. Eu os achei muito úteis em minha programação e as pessoas que herdam meu código estão agradecidas por tê-las.
É uma das maneiras mais visíveis de documentar seu código.
É difícil encontrar o código fonte para ler a documentação em linha ou desenterrar um documento sobre o código. Se você pode ter algo útil através da inteligência, as pessoas vão amá-lo.
"It has to be Used Very much, like me ;)"
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 com 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) .
using them except for libraries
Essa é a hora em que são úteis. Com a geração da Documentação XML ativada e uma referência à montagem, sem o seu projeto, mostrará mais detalhes no intellisense.
Mas para os internos do projeto atual, eles apenas atrapalham.
Eu os uso, mas como outras pessoas disseram não universalmente. Para métodos pequenos, eles podem facilmente ser maiores do 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, de modo que elas 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 para ser escrito em algum lugar, o código é o lugar onde é mais provável que ele fique atualizado (mais provável do que alguns documentos do Word flutuando).
Eu uso o equivalente em VB (já que eles não me deixam usar o C # - aparentemente é muito difícil ... nenhum comentário). Eu os acho muito convenientes. Na maior parte do tempo, espero até que o procedimento ou a função seja concluída, 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á - uma solução alternativa ou outra porcaria que eu prefiro não ter em lá, mas não tenho escolha "por agora".) (Sim, eu sei, que "por enquanto" pode durar anos.)
Estou severamente irritado com o código descomentado. Um consultor escreveu a versão inicial de um dos nossos componentes e não comentou nada e sua escolha de nomes deixou a desejar aqui e ali. Ele está fora há mais de um ano e ainda estamos resolvendo as coisas dele (além de trabalhar em nosso próprio material).