¿Cuáles Son Las Mejores Prácticas Para Documentar código C # con comentarios XML?

Estoy revisando un nuevo código que acabo de escribir y agregando comentarios NDoc sytle a mis clases y métodos. Espero generar un documento de estilo MSDN bastante bueno como referencia.

En general, ¿cuáles son algunas buenas pautas al escribir comentarios para una clase y para un método? ¿Qué deberían decir los comentarios del NDoc? ¿Qué no deberían decir?

Me encuentro mirando lo que dicen los comentarios de. NET framework, pero eso pasa de moda rápidamente; si pudiera tener algunas buenas reglas para guiarme, podría terminar mis documentos mucho más rápido.

Author: Esteban Araya, 2010-06-29
Source

8 answers

En los comentarios que se usan para construir la documentación de la API, debes:

  • Explique qué hace el método o la propiedad, por qué existe y explique cualquier concepto de dominio que no sea evidente para el consumidor promedio de su código.

  • Enumere todas las precondiciones para sus parámetros(no puede ser nulo, debe estar dentro de un cierto rango, etc.)

  • Enumere cualquier postcondición que podría influir en cómo las personas que llaman tratan con los valores devueltos.

  • Listar cualquiera excepciones el método puede lanzar (y bajo qué circunstancias).

  • Si existen métodos similares, explique las diferencias entre ellos.

  • Llame la atención sobre cualquier cosa inesperada (como modificar el estado global).

  • Enumere los efectos secundarios, si los hay.

 51
Author: Jeff Sternal,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-07-30 13:21:08

Si terminas con comentarios que no agregan ningún valor, simplemente 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 agregaste absolutamente ningún valor y solo agregaste más código para mantener.

Con demasiada frecuencia el código está lleno de estos comentarios superfluos.

 16
Author: CaffGeek,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2016-08-02 11:48:45

StyleCop proporciona sugerencias para el código y el estilo de comentario. Las sugerencias que da están en línea con el estilo de documentación de MSDN.

En cuanto al contenido del comentario, debe dar al usuario de su código suficiente información sobre qué tipo de comportamiento esperar. También debe responder a las posibles preguntas que el usuario pueda tener. Así que intenta usar tu código como alguien que no sabe nada sobre el código, o mejor aún, pídele a alguien que lo haga.

 6
Author: Niels van der Rest,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 18:03:06

Para propiedades, su comentario debe indicar si la propiedad es de solo lectura, solo escritura o de lectura y escritura. Si nos fijamos en toda la documentación oficial de MS, propiedad doc comentarios siempre comienzan con " Gets ...", "Consigue o fija..."y (muy rara vez, evitar escribir solo propiedades por lo general)" Conjuntos ..."

 5
Author: Matt Greer,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 17:51:48

No olvide lo que es un XML válido. Por ejemplo:

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Error: XML no válido).

 5
Author: Pavel Radzivilovsky,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 21:24:42

Escribo el comentario

para incluir la información que me gustaría saber si yo era el que llamaba a esa función (o instanciaba esa clase).

Escribo el comentario 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 visión general del funcionamiento interno de la función/clase es muy útil.

 2
Author: mikemanne,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 21:19:44

Como se indica en la página de MSDN, utiliza los comentarios de documentación XML para generar documentación automáticamente, de modo que los fabricantes de ti detectan si está escribiendo una API y no desea trabajar dos veces tanto en el código como en la documentación, con el beneficio adicional de mantenerlos sincronizados: 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á una documentación XML a continuación, utilice una herramienta como Sandcastle para generar los documentos completos.

 0
Author: luvieere,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 17:57:39

Una cosa sobre los comentarios es ACTUALIZARLOS. Demasiadas personas alteran una función y luego no cambian el comentario para reflejar el cambio.

 0
Author: Brian,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2010-06-29 17:58:46