.net - programacion - generar documentacion visual studio 2017
Documentación del código: ¿cuánto es demasiado? (14)
¿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 ya 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() . Es todo 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 hacia una nueva capa empresarial, y mi función en este proyecto es preparar el sistema para el mantenimiento por parte de otros desarrolladores, estoy pensando en la documentación de código sólido. Aunque todos estos métodos tienen buenos comentarios en línea, no todos tienen código doco bueno (o ninguno) en forma de comentarios XML. Usando un combo de GhostDoc y Sandcastle (o el Documento X), puedo crear una documentación HTML bastante agradable y publicarla en SharePoint, lo que permitiría a los desarrolladores comprender más acerca de lo que hace el código sin navegar a través del código en sí.
A medida que aumenta la cantidad de documentación en el código, más difícil se vuelve navegar el código. Estoy comenzando a preguntarme si los comentarios XML harán que el código sea más difícil de mantener que, por ejemplo, un //comment más simple sobre cada método.
Estos ejemplos son de la muestra de 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 por usted: ¿Documenta todo su código con comentarios XML con el objetivo de usar algo como NDoc (RIP) o Sandcastle? Si no es así, ¿cómo decide qué obtiene la documentación y qué no? Algo como una API obviamente tendría doco, pero ¿qué tal una base de código que vas a entregar a otro equipo para mantener?
¿Que crees que deberia hacer?
Creo que una buena parte del problema aquí es la sintaxis de documentación XML prolija y cruzada que MS nos ha impuesto (JavaDoc tampoco era mucho mejor). La cuestión de cómo formatearlo es, en gran medida, independiente de cuánto es apropiado.
Usar el 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 para hacer un trabajo razonable y es una buena experiencia de aprendizaje.
La pregunta de cuánto es más difícil. Creo que la idea del código de auto-documentación está bien, si estás investigando para mantener algún código. Si solo es un cliente, no debería necesitar leer el código para entender cómo funciona una función determinada. Mucha información está implícita en los tipos de datos y nombres, por supuesto, pero hay una gran oferta que no lo es. Por ejemplo, pasar una referencia a un objeto le dice lo que 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 mucho más de este tipo de información que debería documentarse de lo que generalmente se reconoce.
Para mí, se requiere documentación en lenguaje natural para describir el propósito de la función, así como cualquier condición previa y posterior de 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 .
Estás alcanzando una división crítica aquí entre aquellos que mantendrán las nuevas bibliotecas y las que consumirán las nuevas bibliotecas.
Si estoy escribiendo una nueva aplicación y utilizaré 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 posiblemente causar problemas si el código se modifica En ese caso, no tendré acceso a ninguna de las características de "autoeducación" 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 eso no tiene activada la función de autocompletar.
Entonces en su código de ejemplo anterior, creo que se ve bien. Las cosas no son demasiado detalladas dentro del código mismo y los nombres son auto documentados. Por otro lado, todos los datos de resumen / parámetros necesarios están ahí para que se pueda construir una pieza de documentación sólida que permita que aquellos que consuman la biblioteca tengan toda la información crítica a su alcance. Lamentablemente, XML es bastante inflado, pero en general, creo que la mayoría de los desarrolladores pueden navegar fácilmente por todo el contenido de resumen y mirar el código real dentro del método.
He visto estándares de codificación que recomiendan no comentar el código de autocomentarios y las sobrecargas de métodos. Mientras que YMMV, suena como una buena manera de alejarse del "Field _numberOfCars es un número entero que representa el número de coches", los comentarios tipo que conducen a la exageración.
Jeff tiene un artículo realmente bueno sobre cómo comentar (o debería decir, sin 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 autodocumentado como sea posible.
Lo que has mostrado es MUY DEMASIADO. Hazte un favor y elimínalo!
En primer lugar, el código debe ser autodocumentado, mediante métodos significativos y nombres de parámetros. En el ejemplo que has mostrado;
El agregado público del cliente (Título del título, FirstName de la cadena, MiddleInitial de la cadena, Apellido de la cadena) es perfectamente comprensible para la intención de lo que está sucediendo, como lo es ''Count''.
Comentarios como este, como usted señaló, es puramente ruido en torno a lo que de otra manera es fácil de leer el código. La mayoría de los desarrolladores se abrirán antes para examinar y usar el código, que acumular a través de la oscura documentación de API autogenerada. ¡Cada vez!
Los comentarios en un encabezado para generar documentación son 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 algo bueno
No te repitas.
- El primer ejemplo debería tener un mejor nombre de método y ningún comentario en absoluto.
- 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 deberían agregar información, no ocultarla en ruido. Y debería haber comentarios, cuando sea necesario en XML. Y donde agregan valor
No quiero ver: "devuelve el recuento" de un método llamado recuento.
Por cierto, de acuerdo con "Código limpio" (Un gran libro, BTW), uno debe evitar el uso de marcas HTML / XML dentro de los comentarios que están incrustados en el código fuente. Incluso si su IDE puede crear documentación hábil cuando se desplaza, se considera demasiado molesto e ilegible cuando solo navega por sus fuentes.
Recientemente realicé un estudio que muestra que si tienes "directivas" importantes, por ejemplo, quien llama debe hacer X "dentro de muchas especificaciones (por ejemplo," este método hace X que significa Y y Z "), existe un riesgo muy alto de que sus lectores perderían las directivas. De hecho, cuando ven una larga documentación, se saltan la lectura de todo.
Por lo menos, separe las cosas importantes o use el etiquetado (pregúnteme si usa Java).
Siempre opto por los comentarios en formato XML / Javadoc, porque me encanta poder explorar la documentación de la API en un formato razonable (HTML generalmente).
Se convierte en un problema para explorar el código fuente real, pero me parece que esto generalmente es un problema menor, ya que Visual Studio generalmente es bastante inteligente sobre el colapso de comentarios XML según sea necesario.
Tiendo a documentar todos los métodos públicos en mi propio código; usar 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 contorno" (es decir, uso el comando Esquema de Visual Studio> Contraer a definiciones).
Nunca he probado Sandcastle, pero realmente aprecio la comodidad proporcionada por Intellisense para los métodos que he comentado XML.
Todas las funciones públicas deben ser claramente comprensibles para alguien que tenga una familiaridad pasajera con su código base, 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 / clase. El nombre debe ser auto explicativo 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 nombres poco claros.
Por lo general, es mejor errar por el lado de los comentarios SI SE ASEGURA DE QUE SON EXACTOS . Los comentarios inexactos y / o inmanejables son peores que no hay comentarios
Entonces aplicando estas reglas:
En su primer ejemplo: "// crear nueva instancia de cliente" es redundante. El código es claro como el cristal. Los otros comentarios son perfectos. Aclaran en qué opera el código / qué son sus resuls
En su segundo ejemplo, los comentarios son un esfuerzo desperdiciado y dificultan su lectura. Todo lo que necesitas hacer es darle a la función un nombre propio. No ese vago "conteo". Eso es un mal nombre.
Todo depende de los estándares que usa su compañía, 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 la tecla "/" 3 veces) en una fila en la parte superior de cualquier sub o función !!).
El primer ejemplo es excesivo, especialmente el par inferior de líneas donde se comenta cada línea. Sin embargo, creo que las cosas en el encabezado de la función pueden ser útiles, porque las usamos aquí mucho. Y parece ser un tanto estándar de lo que puedo decir de muchos otros programadores.
Nadie mencionó que su código no necesita ser inflado, 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 encima de él, o si prefiere solo el resumen (como se fusionó con el archivo separado).
Es mucho más poderoso que el formato basura que es Javadoc y los derivados que encuentras 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).