c# - fuente - generar documentacion visual studio 2017
¿Cuáles son las mejores prácticas para documentar el código C#con comentarios XML? (8)
Estoy revisando un nuevo código que acabo de escribir y agregando comentarios de NDoc a mis clases y métodos. Espero generar un documento de estilo de MSDN bastante bueno para referencia.
En general, ¿cuáles son algunas buenas pautas al escribir comentarios para una clase y un método? ¿Qué deberían decir los comentarios de NDoc? ¿Qué no deberían decir?
Me encuentro mirando lo que dicen los comentarios de .NET framework, pero eso se hace viejo rápidamente; si pudiera tener algunas buenas reglas para guiarme, podría terminar mis documentos mucho más rápido.
Como se indica en la página MSDN , utiliza los comentarios de la documentación XML para generar documentación automáticamente, por lo que los creadores perciben si está escribiendo una API y no desea trabajar dos veces en el código y la documentación, con la ventaja adicional de mantenerlos sincronización: cada vez que cambia el código, modifica los comentarios apropiados y regenera los documentos.
Compile con /doc y el compilador buscará todas las etiquetas XML en el código fuente y creará un archivo de documentación XML, luego usará una herramienta como Sandcastle para generar los documentos completos.
En los comentarios utilizados para compilar la documentación de la API, debe:
Explica qué hace el método o la propiedad, por qué existe y explica los conceptos de dominio que no son evidentes para el consumidor medio de tu código.
Enumera todas las condiciones previas para tus parámetros (no puede ser nulo, debe estar dentro de un cierto rango, etc.)
Enumere cualquier condición posterior que pueda influir en la forma en que los llamantes manejan los valores devueltos.
Enumere cualquier excepción que el método pueda arrojar (y bajo qué circunstancias).
Si existen métodos similares, explica las diferencias entre ellos.
Llama la atención sobre cualquier cosa inesperada (como la modificación del estado global).
Enumere los efectos secundarios, si los hay.
Escribo el comentario <resumen> para incluir la información que me gustaría saber si era yo quien llamaba a esa función (o instanciaba esa clase).
Escribo el comentario <comentarios> para incluir información que me gustaría saber si me asignaron la tarea de depurar o mejorar esa función o clase. Nota: esto no reemplaza la necesidad de buenos comentarios en línea. Pero a veces una descripción general del funcionamiento interno de la función / clase es muy útil.
No olvides qué es un XML válido. Por ejemplo:
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(Error: XML no válido).
Para las propiedades, su comentario debe indicar si la propiedad es de solo lectura, solo escritura o lectura y escritura. Si observas toda la documentación oficial de MS, los comentarios del documento de propiedad siempre comienzan con "Obtiene ...", "Obtiene o establece ..." y (muy raramente, evitan las propiedades de escritura solo) "Conjuntos ..."
Si terminas con comentarios que no agregan ningún valor, son un desperdicio.
Por ejemplo
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
... no agregó absolutamente ningún valor y solo agregó más código para mantener.
Con demasiada frecuencia, el código está plagado de estos comentarios superfluos.
Una cosa sobre los comentarios es ACTUALIZANDO. Demasiadas personas alteran una función y luego no cambian el comentario para reflejar el cambio.
StyleCop proporciona consejos para el estilo de código y comentario. Las sugerencias que brinda están en línea con el estilo de documentación de MSDN.
En cuanto al contenido del comentario, debe darle al usuario de su código suficiente información sobre qué tipo de comportamiento esperar. También debe responder a posibles preguntas que el usuario pueda tener. Intente utilizar su código como alguien que no sabe nada sobre el código, o mejor aún, pídale a otra persona que lo haga.