Al comentar XML consejos para la programación C # [cerrar]

Question

Buena mañana, tarde, tarde o noche (dependiendo de su zona horaria).

Esto es sólo una cuestión general sobre XML comentar en C #. Nunca he sido muy grande en comentar mis programas, siempre he sido más de una variable / propiedad / Namer método detallado y dejar que el código de hablar por sí mismo. Yo escribo comentarios si estoy de codificación algo que es bastante confuso, pero en su mayor parte no escribo un montón de comentarios.

Me estaba haciendo una lectura acerca de los comentarios XML en .NET, Castillo de arena, y el constructor archivo de ayuda en CodePlex y me ha llevado por el camino de querer documentar mi código y generar algo de buena documentación, útiles para aquellos que tienen que cavar en mi código cuando ya no estoy aquí.

Mi pregunta es acerca de las normas y convenciones. ¿Hay una guía de "buena" XML comentar? En caso de que comentar todas las variables y la propiedad? Todos los métodos? básicamente estoy en busca de consejos sobre cómo escribir buenos comentarios que serán compilados por el castillo de arena en una buena documentación para que otros programadores no maldecir mi nombre cuando se acaban de tener que trabajar en mi código.

Gracias de antemano por sus consejos y sugerencias, Scott Vercuski

Answer 1

En lo personal, nos aseguramos de que cada método público y protegido tiene comentarios XML. También le proporcionará Intellisense, y no sólo los usuarios finales documentación de ayuda. En el pasado, también hemos incluido en las declaraciones de ámbito privado, pero no lo siento se requiere el 100%, siempre y cuando los métodos son cortos y en puntos.

No hay que olvidar que existen herramientas para que se comentan más fácil XML tareas:

• GhostDoc -. Comentario herencia y plantillas complemento
• Sandcastle Archivo de ayuda Constructor - Edita los proyectos de castillos de arena a través de una interfaz gráfica de usuario, se puede ejecutar desde una línea de comandos (para la automatización de compilación), y se puede editar MAML los temas de ayuda no derivados de código. (La versión 1.8.0.0 alfa es muy estable y muy mejorado. Han estado utilizando durante aproximadamente un mes, durante 1.7.0.0)

Answer 2

Los comentarios son muy a menudo obsoletas. Esto siempre ha sido un problema. Mi regla de oro:. Cuanto más se necesita trabajar para actualizar un comentario, más rápido que el comentario será obsoleto

XML comentarios son excelentes para el desarrollo de la API. Que funciona bastante bien con Intellisens y pueden tener que generar un documento de ayuda HTML en ningún momento.

Pero esto no es gratuito: mantenimiento de los mismos será difícil (mirar cualquier ejemplo no trivial, usted entenderá lo que quiero decir), por lo que tenderá a ser obsoleta muy rápido. Como resultado, revisar los comentarios XML deben ser agregados a su revisión de código como un control obligatorio y esta comprobación se debe realizar cada vez que un archivo se actualiza.

Bueno, ya que es caro de mantener, ya que una gran cantidad de símbolos no privadas (en desarrollo no API) sólo se utilizan por 1 o 2 clases, y puesto que estos symboles son a menudo explica por sí mismo, nunca podría cumplir una regla que diga que cada símbolo no debe ser privada XML comentó. Esto sería una exageración y conterproductive . Lo que se obtiene es lo que vi en muchos lugares: cerca de comentarios XML vacíos sin añadir nada al nombre symbole. Y el código que es sólo un poco menos legible ...

Creo que el muy, muy importante línea de guía acerca de los comentarios en el código normal (no API) no debe ser sobre cómo deben escribirse , pero sobre lo que deberían contener . Una gran cantidad de desarrolladores todavía no sabemos lo para escribir. Una descripción de lo que debe ser comentado, con ejemplos, haría mejor para el código que sólo una llanura: "No utilizar los comentarios XML en cada symbole no privado".

Answer 3

Yo documento clases públicas y las / Miembros protegidas públicas de esas clases.

Yo no documentan los miembros privados o internos o clases internas. Por lo tanto, las variables (creo que se refiere a los campos), ya que son privadas.

El objetivo es crear algún tipo de documentación para un desarrollador que no tiene fácil acceso al código fuente.

Endeavour para colocar algunos ejemplos donde el uso no es obvia.

Answer 4

Muy rara vez comentar sobre las variables del método, e igualmente rara vez (si no existiera ya que suelen estar cubiertos por una propiedad, o simplemente si el uso de las propiedades de auto-aplicado) Campos.

En general, me esfuerzo para añadir comentarios significativos a todos los miembros públicos / protegidas, lo cual es muy útil, ya que si se encienden los comentarios XML durante la construcción, se obtiene advertencias automáticas para la falta de comentarios. Dependiendo de la complejidad, puede que no llene todos los detalles - es decir, si es 100% obvio lo que todos los parámetros tiene que hacer (es decir, no hay una lógica especial, y sólo hay 1 manera lógica de interpretar las variables), entonces podría da pereza y no añadir comentarios sobre los parámetros.

Pero luego, tratar de describir qué métodos, tipos, propiedades, etc representar / do.

Answer 5

A continuación se documentan los métodos / propiedades públicas / etc en nuestras bibliotecas. Como parte del proceso de formación usamos NDoc para crear una referencia Web MSDN-como. Ha sido muy útil para una referencia rápida y de búsqueda.

También es ideal para Intellisense, especialmente con los nuevos miembros del equipo o, como usted ha dicho, cuando el autor original se ha ido.

Estoy de acuerdo que el código, en general, debe explicarse por sí mismo. El documention XML, para mí, es más acerca de referencia y de consulta cuando no tiene el código abierto.

Answer 6

En lo personal mi opinión es evitar hacer comentarios. Al comentar es peligroso. Debido a que en la industria siempre actualizar el código (debido a los requerimientos del negocio y están en constante cambio), pero varían raramente actualizamos nuestras observaciones. Esto puede confundir a los programadores.