dicas Comentando XML para C # programação [fechado]

Question

Bom dia, tarde, noite ou da noite (dependendo do fuso horário).

Esta é apenas uma questão geral sobre XML comentando dentro C #. Eu nunca fui muito grande para comentar os meus programas, eu sempre fui mais de uma propriedade / namer variável detalhado / método e deixando a falar código para si. Eu faço comentários escrever, se eu estou codificação algo que é bastante confuso, mas na maioria das vezes eu não escrevo um monte de comentários.

eu estava fazendo alguma leitura sobre comentários XML em .NET, Castelo de areia, eo construtor arquivo de ajuda no CodePlex e me levou para o caminho de querer documentar meu código e gerar algum bom, documentação útil para aqueles que têm de escavação em meu código quando eu não estou mais aqui.

A minha pergunta é sobre normas e convenções. Existe um guia para "bom" XML comentando? Se você comentar todas as variáveis ??e propriedade? Cada método? Eu só estou basicamente procurando dicas sobre como escrever bons comentários que serão compiladas pelo castelo de areia em uma boa documentação para que outros programadores não amaldiçoar o meu nome quando eles acabam por ter de trabalhar no meu código.

Agradecemos antecipadamente por sua assessoria e sugestões, Scott Vercuski

Answer 1

Pessoalmente, nós temos certeza que cada público e método protegido tem comentários XML. Ele também irá lhe fornecer Intellisense, e do usuário final não apenas documentação de ajuda. No passado, temos também incluiu em declarações escopo em particular, mas não sinto que é 100% necessário, desde que os métodos são curtos e on-ponto.

Não se esqueça que existem ferramentas para torná-lo XML comentando tarefas mais fáceis:

• GhostDoc -. Comment herança e templates add-in
• Arquivo Sandcastle Ajuda Builder - Edita os projectos Sandcastle através de uma GUI, pode ser executado a partir de uma linha de comando (para automação de compilação), e pode editar MAML para tópicos de ajuda não derivado de código. (A versão 1.8.0.0 alpha é muito estável e muito melhorada. Foram usá-lo por cerca de um mês, mais de 1.7.0.0)

Answer 2

Os comentários são muitas vezes ultrapassada. Este sempre foi um problema. Minha regra de ouro:. Quanto mais você precisa de trabalho para atualizar um comentário, mais rápido que o comentário será obsoleto

comentários XML são grandes para o desenvolvimento API. Eles funciona muito bem com Intellisens e podem ter você gerar um documento de ajuda HTML em nenhum momento.

Mas isso não é livre: mantê-los será difícil (olhada em qualquer exemplo não-trivial, você vai entender o que quero dizer), então eles tendem a ser ultrapassada muito rapidamente. Como resultado, revendo XML Os comentários devem ser adicionados à sua revisão de código como uma verificação obrigatória e esta verificação deve ser realizada cada vez que um arquivo é atualizado.

Bem, uma vez que é caro para manter, uma vez que muitos símbolos não privados (em desenvolvimento não-API) são usados ??apenas por 1 ou 2 classes, e uma vez que estes symboles são muitas vezes auto-explicativo, eu nunca iria impor uma governar dizendo que cada símbolo não-privada deve ser XML comentou. Este seria um exagero e conterproductive . O que você vai conseguir é o que eu vi em um monte de lugares: quase vazio comentários XML adicionando nada para o nome symbole. E código que é apenas um pouco menos legível ...

Eu acho que o muito, muito importante linha de orientação sobre os comentários no código normal (não-API) não deve ser sobre como eles devem ser escritos , mas sobre O que eles devem conter . Um monte de desenvolvedores ainda não sabem o para gravação. Uma descrição do que deve ser comentado, com exemplos, seria melhor para o seu código do que apenas um simples: "Não uso XML Comentários em todos os symbole não-privada".

Answer 3

Eu documentar classes públicas eo público / membros protegidos dessas classes.

Eu não documentar membros privados ou internos ou classes internas. Daí variáveis ??(eu acho que você campos médios), porque eles são privados.

O objetivo é criar alguma documentação para um desenvolvedor que não tem pronto acesso ao código-fonte.

Endeavour para colocar alguns exemplos onde o uso não é óbvia.

Answer 4

I muito raramente comentário sobre as variáveis ??do método, e igualmente raramente campos (uma vez que são normalmente cobertos por uma propriedade, ou simplesmente não existem, se usando as propriedades implementadas através de auto).

Geralmente eu dou duro para adicionar comentários significativos a todos os / membros protegidas públicas, que é útil, pois se você ligar os comentários xml durante a compilação, você recebe avisos automáticos para faltando comentários. Dependendo da complexidade, eu poderia não preencher todos os detalhes - ou seja, se ele é 100% claro o que cada parâmetro tem para fazer (ou seja, não existe uma lógica especial, e há apenas uma maneira lógica de interpretação as variáveis), então eu pode ficar com preguiça e não adicionar comentários sobre os parâmetros.

Mas eu certamente tentar descrever o que métodos, tipos, propriedades, etc representar / fazer.

Answer 5

Nós documentar os métodos / propriedades públicas / etc em nossas bibliotecas. Como parte do processo de construção usamos NDoc para criar uma referência web MSDN-like. Tem sido muito útil para referência rápida e de pesquisa.

Também é ótimo para Intellisense, especialmente com novos membros da equipe ou, como você disse, quando o autor original não existe mais.

Eu concordo que o código, em geral, deve ser auto-explicativo. O documention XML, para mim, é mais sobre a referência e pesquisa quando você não tem o código aberto.

Answer 6

Pessoalmente minha opinião é evitar comentar. Comentando é perigoso. Porque na indústria nós sempre atualizar o código (porque os requisitos de negócio e estão sempre mudando), mas variam raramente nós atualizamos nossos comentários. Isso pode desencaminhar os programadores.