Documentación del código: ¿Cuánto es demasiado?

Question

¿Cuánta documentación de código en su fuente .NET es demasiado?

Algunos antecedentes: heredé una gran base de código de la que he hablado en algunas de las otras preguntas que publiqué aquí en SO. Una de las '' características '' de esta base de código es una clase de Dios, una única clase estática con > 3000 líneas de código que abarca varias docenas de métodos estáticos. Es todo, desde Utilities.CalculateFYBasedOnMonth () a Utilities.GetSharePointUserInfo () a Utilities.IsUserIE6 () . Todo es un buen código que no necesita ser reescrito , solo refactorizado en un conjunto apropiado de bibliotecas. Tengo eso planeado.

Dado que estos métodos se están moviendo a una nueva capa empresarial, y mi función en este proyecto es preparar el sistema para que otros desarrolladores lo mantengan, estoy pensando en una documentación de código sólido. Si bien todos estos métodos tienen buenos comentarios en línea, no todos tienen un buen (o ningún) código doco en forma de comentarios XML. Utilizando un combo de GhostDoc y Sandcastle (o Documento X), puedo crear una documentación HTML bastante agradable y publicarla en SharePoint, lo que permitiría a los desarrolladores comprender más sobre lo que hace el código sin navegar a través del código mismo.

A medida que aumenta la cantidad de documentación en el código, más difícil resulta navegar el código. Estoy empezando a preguntarme si los comentarios XML harán que el código sea más difícil de mantener que, digamos, un // comment más simple en cada método.

Estos ejemplos son de la muestra del 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;
        }

Y:

    /// <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;
        }
    }

Así que me preguntaba de usted: ¿documenta todo su código con comentarios XML con el objetivo de utilizar algo como NDoc (RIP) o Sandcastle? Si no es así, ¿cómo decide qué obtiene documentación y qué no? Algo así como una API obviamente tendría doco, pero ¿qué pasa con una base de código que vas a entregar a otro equipo para mantener?

¿Qué crees que debería hacer?

Answer 1

Creo que una buena parte del problema aquí es la sintaxis de documentación XML detallada y cruda que MS nos ha impuesto (JavaDoc tampoco fue mucho mejor). La cuestión de cómo formatearlo es, en gran medida, independiente de cuánto es apropiado.

El uso del formato XML para comentarios es opcional. Puede usar DOxygen u otras herramientas que reconocen diferentes formatos. O escriba su propio extractor de documentos: no es tan difícil como podría pensar hacer un trabajo razonable y es una buena experiencia de aprendizaje.

La cuestión de cuánto es más difícil. Creo que la idea del código autodocumentado está bien, si está buscando algo para mantener el código. Si solo es un cliente, no debería necesitar leer el código para comprender cómo funciona una función determinada. Mucha información está implícita en los tipos y nombres de datos, por supuesto, pero hay una gran cantidad de información que no lo es. Por ejemplo, pasar una referencia a un objeto le dice qué se espera, pero no cómo se manejará una referencia nula. O en el código del OP, cómo se maneja cualquier espacio en blanco al principio o al final de los argumentos. Creo que hay lejos más de este tipo de información que debería documentarse de lo que generalmente se reconoce.

Para mí, requiere documentación en lenguaje natural para describir el propósito de la función, así como cualquier condición previa y posterior para la función, sus argumentos y valores de retorno que no se pueden expresar a través de la sintaxis del lenguaje de programación .

Answer 2

Nadie mencionó que su código no necesita ser hinchado, la documentación XML puede estar en otro archivo:

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

Y luego su método Add no puede contener XML / comentarios adicionales sobre él, o si prefiere solo el resumen (ya que se fusionó con el archivo separado).

Es mucho más poderoso que el formato basura que es Javadoc y derivados que se encuentran en PHP / Javascript (aunque Javadoc allanó el camino para la sintaxis XML). Además, las herramientas disponibles son muy superiores y el aspecto predeterminado de los documentos de ayuda es más legible y más fácil de personalizar (puedo decirlo por haber escrito doclets y comparar ese proceso con Sandcastle / DocProject / NDoc).

Answer 3

Aquí está llegando a una división crítica entre los que mantendrán las nuevas bibliotecas y los que consumirán las nuevas bibliotecas.

Si estoy escribiendo una nueva aplicación y usaré estas bibliotecas estándar, debería obtener un binario estable de las bibliotecas y simplemente importarlas a mi aplicación, no copiar el código fuente desde una ubicación y potencialmente causar problemas Si el código se modifica. En ese caso, no tendré acceso a ninguno de los "autodocumentados" características que no sean el nombre del método y los parámetros de entrada / salida, e incluso esos no estarán expuestos si estoy usando algún tipo de IDE que no tenga activada la función de autocompletar.

Entonces, en su código de ejemplo anterior, creo que se ve muy bien. Las cosas no son demasiado detalladas dentro del propio código y los nombres se documentan por sí mismos. Por otro lado, todos los datos de resumen / parámetros necesarios están allí para que se pueda construir una pieza de documentación sólida que permita a quienes consumen la biblioteca tener toda la información crítica a su alcance. Lamentablemente, XML está bastante hinchado, pero en general creo que la mayoría de los desarrolladores pueden navegar fácilmente por todo el contenido de resumen y buscar el código real dentro del método.

Answer 4

Jeff tiene un muy buen artículo sobre comentar (o debería decir, no comentar) aquí ...

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

Sé que parece que no estoy respondiendo la pregunta, pero creo que es un punto válido que el código debe ser tan autodocumentable como sea posible.

Answer 5

Tiendo a documentar todos los métodos públicos en mi propio código; El uso de GhostDoc hace que esto sea trivial. Y para reducir el desorden cuando edito mi código fuente, generalmente solo colapso los comentarios yendo primero al "modo de esquema". (es decir, use el esquema de Visual Studio > Contraer para el comando de definiciones).

Nunca he probado Sandcastle, pero realmente aprecio la comodidad que proporciona Intellisense para los métodos que he comentado con XML.

Answer 6

Siempre opto por los comentarios en formato XML / Javadoc, porque me encanta poder examinar la documentación de la API en un formato sensible (HTML generalmente).

Se convierte en un problema para explorar el código fuente real, pero encuentro que esto generalmente es un problema menor, ya que Visual Studio es generalmente bastante inteligente al contraer los comentarios XML según sea necesario.

Answer 7

No te repitas.

• El primer ejemplo debería tener un mejor nombre de método y ningún comentario.
• El segundo ejemplo no debería tener un comentario.

El nombre del primer método debe reflejar que se asigna un nuevo objeto.

Si ese comportamiento es estándar en todo el marco para cada complemento, debe documentarse en un nivel superior, no en este método API doc. De lo contrario, cambie el nombre.

Los comentarios deben agregar información, no ocultarla en el ruido. Y debería haber comentarios, cuando sea necesario en XML. Y donde agregan valor.

No quiero ver: " devuelve el recuento " para un método llamado recuento.

Answer 8

Todas las funciones públicas deben ser claramente comprensibles para alguien que tenga una familiaridad pasajera con su base de código, pero NO en su sección específica sin tener que profundizar en el código.

Si necesita escribir una línea corta para explicar lo que hace una función, es probable que haya nombrado mal su función / clases. El nombre debe explicarse por sí mismo en ese caso

Si requiere más de 1 breve oración para explicar, probablemente sea un buen comentario

Si toma un párrafo, su función probablemente esté haciendo demasiado, además de los nombres poco claros.

Por lo general, es mejor equivocarse al lado de los comentarios SI SE ASEGURA DE QUE SON EXACTOS . Los comentarios inexactos y / o imposibles de mantener son peores que ningún comentario

Entonces aplicando estas reglas:

En su primer ejemplo: " // crea una nueva instancia de cliente " Es redundante. El código es claro como el cristal. Los otros comentarios son perfectos. Aclaran sobre qué opera el código / cuáles son sus resultados

En su segundo ejemplo, los comentarios son un esfuerzo inútil y dificultan la lectura. Todo lo que necesita hacer es darle a la función un nombre propio. No es tan vago `` contar ''. Esa es una mala denominación.

Answer 9

Recientemente realicé un estudio que muestra que si tiene importantes "directivas", por ejemplo, la persona que llama debe hacer X ". Dentro de una gran cantidad de especificaciones (por ejemplo, "este método hace X, que significa Y y Z"), existe un riesgo muy alto de que sus lectores se pierdan las directivas. De hecho, cuando ven una larga documentación, dejan de leerla por completo.

Entonces, al menos, separe las cosas importantes o use etiquetado (pregúnteme si usa Java).

Answer 10

Todo depende de los estándares que utiliza su empresa, pero para mi equipo, documentamos en la parte superior de cada función, como en su segundo ejemplo (que por cierto puede hacer en Visual Studio 2008 presionando el " / " tecla 3 veces seguidas en la parte superior de cualquier sub o función !!).

El primer ejemplo es exagerado, especialmente el par de líneas inferiores donde se comenta cada línea. Sin embargo, creo que las cosas en el encabezado de la función podrían ser útiles, porque lo usamos mucho aquí. Y parece ser algo estándar de lo que puedo decir de muchos otros programadores.

Answer 11

He visto estándares de codificación que recomiendan no hacer comentarios sobre el código de auto comentario y sobrecargas de métodos. Si bien YMMV, parece una buena manera de alejarse del " Field _numberOfCars es un número entero que representa la cantidad de comentarios de tipo de automóviles " que conducen a una exageración.

Answer 12

Los comentarios en un encabezado para generar documentación es algo bueno. Poner comentarios en el código para explicar por qué estás haciendo lo que estás haciendo también suele ser algo bueno. Hacer comentarios redundantes parafraseando lo que hiciste no es bueno

Answer 13

Lo que has mostrado es MUCHO DEMASIADO. ¡Hazte un favor y bórralo!

El código primero debe ser autodocumentado, a través de nombres de parámetros y métodos significativos. En el ejemplo que has mostrado;

Public Customer Add (Title Title, string FirstName, string MiddleInitial, string LastName) es perfectamente comprensible para la intención de lo que está sucediendo, al igual que 'Count'.

Un comentario como este, como usted señaló, es puramente ruido en torno a lo que de otro modo sería un código fácil de leer. La mayoría de los desarrolladores abrirán antes el examen y el uso del código, que lo acumularán en la oscura documentación de la API generada automáticamente. ¡Cada vez!

Answer 14

Por cierto, de acuerdo con " Código limpio " (Un gran libro, por cierto), uno debe evitar el uso de marcas HTML / XML en los comentarios que están incrustados en el código fuente. Incluso si su IDE puede crear documentación ingeniosa cuando pasa el mouse, se considera demasiado molesto e ilegible cuando solo navega por sus fuentes.