¿Cuáles son las mejores prácticas para la documentación de código C # con comentarios XML?

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

  •  01-10-2019
  •  | 
  •  

Pregunta

Estoy pasando por un nuevo código que acabo de escribir y añadir comentarios NDoc sytle a mis clases y métodos. Tengo la esperanza de generar un documento estilo bastante bueno MSDN para referencia.

En general, ¿cuáles son algunas directrices al escribir buenos comentarios de una clase y de un método? ¿Qué deben decir los comentarios NDoc? ¿Qué deben decir no?

Me encuentro mirando lo que dicen los comentarios del marco .NET, pero que envejece rápidamente; si pudiera tener algunas buenas reglas para guiar a mí mismo, que pudiera terminar mis documentos mucho más rápido.

¿Fue útil?

Solución

En los comentarios se utilizan para documentación de la versión de la API, debe:

  • explicar lo que hace el método o propiedad, por lo que existe, y explicar cualquier concepto de dominio que no son evidentes para el consumidor medio de su código.

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

  • Detalle las condiciones posteriores que podrían influir en cómo las personas que llaman se ocupan de valores de retorno.

  • Lista de cualquier excepción, el método puede lanzar (y en qué circunstancias).

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

  • llamar la atención sobre algo inesperado (como la modificación de estado global).

  • Enumerar los efectos secundarios, si los hay.

Otros consejos

Si usted termina con los comentarios que no aportan ningún valor, son simplemente 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)

... se añade ningún valor y se agregó más código de mantener.

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

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

En cuanto a los contenidos del comentario, se debe dar al usuario de su código de suficiente información sobre qué tipo de comportamiento a esperar. También debe responder a las preguntas posibles que el usuario pueda tener. Así que trate de utilizar su código como alguien que no sabe nada sobre el código, o mejor aún, pedir a alguien más para hacerlo.

Para las propiedades, su comentario debe indicar si la propiedad es de sólo lectura, de escritura o de lectura y escritura. Si nos fijamos en todos los documentos oficiales MS, comentarios doc propiedad siempre comienzan con "Obtiene ...", "Obtiene o establece ..." y (muy rara vez, evite escribir sólo las propiedades por lo general) "Conjuntos ..."

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

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

(error: XML no válido).

escribo el

comentario para incluir la información que me gustaría saber si yo era el que llamar a esa función (o una instancia de esa clase).

escribir el comentario para incluir la información que me gustaría saber si yo tenía la tarea de depuración 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 de los mecanismos internos de la función / clase son muy útiles.

Como se indica en la MSDN página , se utiliza la documentación XML comentarios para generar la documentación de forma automática, por lo que los fabricantes de sentido si se está escribiendo una API y no quieren el trabajo dos veces en el código y la documentación, con la ventaja añadida de mantener sincronizados - cada vez que cambie el código, se modifica las observaciones pertinentes y regenerar los docs.

Compilar con /doc y el compilador va a buscar todas las etiquetas XML en el código fuente y crear un archivo de documentación XML, a continuación, utilizar una herramienta como castillo de arena para generar los documentos completos.

Una cosa acerca de los comentarios que se está actualizando. Hay demasiadas personas que alteran una función entonces no cambiar el comentario para reflejar el cambio.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top