documentação de código: Quanto é demais?

StackOverflow https://stackoverflow.com/questions/288298

Pergunta

Quanto documentação de código em sua fonte .NET é demais?

Alguns antecedentes: Eu herdei uma grande base de código que eu tenho falado em alguns dos outros perguntas que eu postei aqui no SO. Uma das "características" deste código base é uma classe de Deus, uma classe estática única com> 3000 linhas de código que engloba vários métodos dúzia estáticos. É de tudo, desde Utilities.CalculateFYBasedOnMonth() para Utilities.GetSharePointUserInfo() para Utilities.IsUserIE6(). É tudo bom código que não precisa ser reescrito , apenas reformulado em um apropriado conjunto de bibliotecas. Eu tenho que planejado.

Uma vez que esses métodos estão se movendo para uma nova camada de negócios, e meu papel neste projeto é preparar o sistema para manutenção por outros desenvolvedores, eu estou pensando sobre documentação de código sólida. Embora estes métodos têm bons comentários na linha, eles não têm bom (ou qualquer) doco código na forma de comentários XML. Usando uma combinação de GhostDoc e Sandcastle (ou Documento X), eu posso criar alguma documentação bastante agradável HTML e postá-lo para o SharePoint, o que permitiria que os desenvolvedores a entender mais sobre o que o código faz sem navegar através do próprio código.

Como a quantidade de documentação nos código aumenta, mais difícil se torna para navegar o código. Estou começando a me perguntar se os comentários XML vai tornar o código mais difícil de manter do que, digamos, um //comment mais simples faria em cada método.

Estes exemplos são a partir da amostra documento X: 

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

E: 

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

Então eu queria saber de você: você documento todas do seu código com comentários XML com o objetivo de utilizar algo como NDoc (RIP) ou Sandcastle? Se não, como você decide o que recebe a documentação eo que não funciona? Algo como uma API, obviamente, teria doco, mas que sobre uma base de código que você vai entregar para outra equipe para manter?

O que você acha que devo fazer?

Foi útil?

Solução

Eu acho que uma boa parte do problema aqui é o detalhado e MS sintaxe de documentação XML intrincada tem impingido sobre nós (JavaDoc não era muito melhor, quer). A questão de como formatar é, em grande medida, independente de quanto é apropriado.

Usando o formato XML para comentários é opcional. Você pode usar Doxygen ou outras ferramentas que reconhecem diferentes formatos. Ou escreve sua própria extractor documento -. Não é tão difícil como se poderia pensar em fazer um trabalho razoável e é uma experiência boa aprendizagem

A questão de quanto é mais difícil. Eu acho que a idéia de código de auto-documentação é bom, se você está cavando em manter algum código. Se você é apenas um cliente, você não precisa ler o código para entender como uma determinada função funciona. Muita informação está implícita nos tipos de dados e nomes, é claro, mas há muita coisa que não é. Por exemplo, passando uma referência a um objeto lhe diz o que é esperado, mas não como uma referência nula serão tratadas. Ou no código do OP, como qualquer espaço em branco no início ou no final dos argumentos são manipulados. Eu acredito que há muito mais deste tipo de informação que deve ser documentado do que é geralmente reconhecido.

Para mim, isso requer documentação de linguagem natural para descrever a finalidade da função, bem como quaisquer pré e pós-condições para a função, os seus argumentos, e valores de retorno , que não podem ser expressas através da sintaxe da linguagem de programação .

Outras dicas

Ninguém é mencionado o seu código não precisa ser inchado, a documentação XML pode estar em outro arquivo: 

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

E, em seguida, o seu método Add não pode conter XML de cama / comentários acima dele, ou se preferir apenas o resumo (como isso é mesclado com o arquivo separado).

É muito mais poderoso do que o formato de lixo que é Javadoc e derivados você encontra em PHP / Javascript (embora Javadoc abriu o caminho para a sintaxe XML). Além disso, as ferramentas disponíveis são muito superiores e a aparência padrão dos documentos de ajuda é mais legível e mais fácil de personalizar (posso dizer que de ter doclets escritas e comparar esse processo ao Sandcastle / DocProject / NDoc).

Você está batendo uma divisão crítica aqui entre aqueles que serão manter as novas bibliotecas e aqueles que estará consumindo as novas bibliotecas.

Se eu estou escrevendo uma nova aplicação e estará usando essas bibliotecas padrão, eu deveria estar recebendo um binário estável das bibliotecas e simplesmente importá-los para a minha candidatura, não basta copiar o código fonte para baixo a partir de uma localização e potencialmente causando problemas Se o código é modificado. Nesse caso, não terá acesso a qualquer um dos "auto documentar" apresenta diferente do nome do método e os parâmetros de entrada / saída, e mesmo aqueles que não será exposto se eu estou usando algum tipo de IDE que não tem a completa auto caracterizou ligado.

Assim, no seu código de exemplo acima, eu acho que parece muito bem. As coisas não são muito detalhado dentro do próprio código e os nomes são auto documentar. Por outro lado, todos os dados de resumo / parâmetro necessárias existe para que um sólido pedaço de documentação poderia ser construída para permitir que aqueles que consomem a biblioteca para ter toda a informação crítica na ponta dos dedos. Infelizmente XML é bastante inchado, mas em grande eu acho que a maioria dos desenvolvedores pode direita facilmente navegar por todo o conteúdo resumo e olhar para o código real dentro do método.

Jeff tem um artigo muito bom sobre comentando (ou devo dizer, não comentar) aqui ...

http://www.codinghorror.com/blog/archives/001150.html

Eu sei que parece que eu não estou respondendo a pergunta, mas eu acho que é um ponto válido que o código deve ser tão auto-documentado quanto possível.

I tendem a documentar todos os métodos públicos em meu próprio código; usando GhostDoc torna este trivial. E, a fim de reduzir a desordem quando eu editar o meu código fonte, eu geralmente apenas contraia os comentários, indo pela primeira vez em "modo de estrutura" (ou seja, usar Visual Esboço de um contexto> Fechar para comando definições).

Eu nunca tentei Sandcastle, mas eu realmente aprecio o conforto proporcionado pelo Intellisense para os métodos que tenho comentou-XML.

Eu sempre opt para os comentários XML / formato Javadoc, porque eu amo ser capaz de navegar documentação da API em um formato sensível (HTML normalmente).

Ele se torna um problema para navegar o código fonte real, mas acho que este é geralmente uma questão menor, uma vez que Visual Studio é geralmente muito inteligente sobre o colapso comentários XML conforme necessário.

Não repetir-se.

  • O primeiro exemplo deve ter um nome melhor método e comentários em tudo.
  • O segundo exemplo não deve ter um comentário.

O nome do primeiro método deve refletir que um novo objeto é alocado.

Se esse comportamento é padrão em toda a estrutura para cada add, deve ser documentada em um nível mais alto, não neste doc método API. Caso contrário, altere o nome.

Os comentários devem agregar informação, não escondê-lo em ruído. E deve haver comentários, se necessário em XML. E onde agregar valor.

Eu não quero ver: "Retorna a contagem" para um método de contagem de chamada.

Todas as funções públicas deve ser claramente compreensível por alguém que tem uma familiaridade com a sua base de código, mas não na sua seção específica sem ter que mergulhar no código.

Se você precisa escrever uma linha curta para explicar o que a função faz, as chances são que você nomeou suas funções / classes mal. O nome deve ser auto-explicativo, nesse caso

Se precisar de mais de 1 breve frase para explicar, isso é provavelmente uma boa comentário

Se demorar um parágrafo, a sua função é, provavelmente fazendo muito além provável nomes pouco claras.

Geralmente é melhor errar do lado dos comentários Se você se certificar eles são precisos . comentários imprecisos e / ou insustentável são piores do que comentários

Assim, a aplicação destas regras:

Em seu primeiro exemplo: "// cria nova instância do cliente" é redundante. O código é cristalina. Os outros comentários são perfeitos. Eles esclarecer o que o código está operando em cima / o que é resuls são

Em seu segundo exemplo os comentários são desperdiçados esforço e torná-lo difícil de ler. Tudo que você precisa fazer é dar a função de um nome próprio. Não que "contar" vago. Isso é de nomenclatura pobres.

Recentemente, realizou um estudo que mostra que se você tem "directivas 'importantes por exemplo, Caller deve fazer X' dentro de um monte de especificações (por exemplo, 'este método X que significa Y e Z'), há uma alto risco de que seus leitores iria perder as directivas. Na verdade, quando vêem uma documentação muito tempo, eles pular de lê-lo todos juntos.

Assim, pelo menos, separar o importante coisas ou o uso de marcação (me pergunte se você usa Java).

Tudo depende dos padrões de sua empresa está usando, mas para minha equipe, documentamos no topo de cada função como em seu segundo exemplo (que pela maneira que você pode fazer em Visual Studio 2008 por bater o "/" -chave 3 vezes seguidas no topo de qualquer sub ou função !!).

O primeiro exemplo é um exagero, especialmente o par inferior de linhas em que cada linha é comentado. No entanto, acho que o material no cabeçalho da função pode ser embora útil, porque nós usá-lo muito aqui. E isso parece ser um pouco padrão do que eu posso dizer a partir de lotes de outros programadores.

eu vi padrões de codificação que recomendam contra comentando código e método sobrecargas auto-comentando. Enquanto YMMV, soa como uma boa maneira de ficar longe das "_numberOfCars campo é um inteiro que representa o número de carros", comenta -tipo que chumbo em exagero.

Comentários em um cabeçalho para a documentação de geração é uma coisa boa. Colocar comentários no código para explicar por que você está fazendo o que está fazendo também é geralmente uma boa coisa. Colocando em comentários redundantes parafraseando o que você fez não é uma coisa boa

O que você tem mostrado é demais. Fazer o auto um favor e excluí-lo!

Código deve em primeiro lugar ser auto documentar, através de nomes de métodos e parâmetros significativos. No exemplo que você tem mostrado;

Add pública Cliente (Título Título, corda FirstName, corda MiddleInitial, corda LastName) é perfeitamente compreensível à intenção do que está acontecendo, como é 'Conde'.

Ao comentar como esta, como você apontou, é puramente ruído em torno do que é de outra maneira fácil de ler código. A maioria dos desenvolvedores, mais cedo aberto até examinar e usar o código, que pilha através de documentação da API gerada automaticamente obscura. Toda vez!

A propósito, de acordo com o "código Clean" (Um grande livro, BTW), deve-se evitar o uso de marcações HTML / XML dentro dos comentários que são incorporados no código fonte. Mesmo que o seu IDE pode criar documentação bacana quando você passa, ele é considerado muito distraindo e ilegível quando você simplesmente navegar suas fontes.

Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top