remarks - Consejos sobre XML Commenting para la programación de C#

remarks c# (6)

Buenos días, tarde, tarde o noche (dependiendo de su zona horaria).

Esta es solo una pregunta general sobre los comentarios XML dentro de C #. Nunca he sido muy bueno para comentar mis programas, siempre he sido más una variable / propiedad / método detallado y me gusta dejar que el código hable por sí mismo. Escribo comentarios si estoy codificando algo que es bastante confuso, pero la mayoría de las veces no escribo muchos comentarios.

Estuve leyendo sobre los comentarios de XML en .NET, Sandcastle y el creador de archivos de ayuda en codeplex, y me ha llevado por el camino de querer documentar mi código y generar una documentación útil y útil para aquellos que tienen que cavar en mi código cuando ya no estoy aquí.

Mi pregunta es sobre estándares y convenciones. ¿Hay alguna guía sobre los comentarios XML "buenos"? ¿Deberías comentar CADA variable y propiedad? CADA método? Básicamente estoy buscando consejos sobre cómo escribir buenos comentarios que Sandcastle compilará en buena documentación para que otros programadores no maldigan mi nombre cuando terminan trabajando en mi código.

Gracias de antemano por sus consejos y sugerencias, Scott Vercuski

Documentamos los métodos / propiedades / etc públicos en nuestras bibliotecas. Como parte del proceso de compilación, utilizamos NDoc para crear una referencia web similar a MSDN. Ha sido muy útil para referencia rápida y búsqueda.

También es excelente para Intellisense, especialmente con nuevos miembros del equipo o, como dijiste, cuando el autor original se ha ido.

Estoy de acuerdo en que el código, en general, debería ser autoexplicativo. La documentación XML, para mí, se trata más de referencia y búsqueda cuando no tiene la fuente abierta.

Documentar las clases públicas y los miembros públicos / protegidos de esas clases.

No documento miembros privados o internos o clases internas. De ahí las variables (creo que te refieres a los campos) porque son privadas.

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

Procure colocar algunos ejemplos donde el uso no sea obvio.

Personalmente, nos aseguramos de que todos los métodos públicos y protegidos tengan comentarios XML. También le proporcionará Intellisense, y no solo la documentación de ayuda del usuario final. En el pasado, también lo hemos incluido en declaraciones de alcance privado, pero no creemos que sea 100% obligatorio, siempre que los métodos sean cortos y estén en el punto.

No olvide que hay herramientas para facilitarle las tareas de comentarios en XML:

GhostDoc - Herencia de comentarios y complemento de plantillas.
Constructor de archivos de ayuda de Sandcastle : edita los proyectos de Sandcastle a través de una GUI, se puede ejecutar desde una línea de comandos (para automatización de compilación) y puede editar MAML para temas de ayuda que no se derivan del código. (La versión 1.8.0.0 alpha es muy estable y muy mejorada. Hace un mes que la utilizo, más de 1.7.0.0)

Raramente hago comentarios sobre variables de método, y campos igualmente raros (ya que generalmente están cubiertos por una propiedad, o simplemente no existen si se usan propiedades implementadas automáticamente).

En general, trato de agregar comentarios significativos a todos los miembros públicos / protegidos, lo cual es útil, ya que si activas los comentarios xml durante la compilación, obtienes advertencias automáticas por los comentarios que faltan. Dependiendo de la complejidad, es posible que no complete todos los detalles, es decir, si es 100% obvio lo que tiene que hacer cada parámetro (es decir, no hay una lógica especial, y solo hay 1 forma lógica de interpretar las variables), entonces podría obtienes pereza y no agregas comentarios sobre los parámetros.

Pero ciertamente intento describir qué métodos, tipos, propiedades, etc. representan / hacen.

Personalmente mi opinión es evitar comentar. Comentar es peligroso. Porque en la industria siempre actualizamos el código (porque el negocio y los requisitos siempre cambian), pero raramente actualizamos nuestros comentarios. Esto puede confundir a los programadores.

Los comentarios a menudo están desactualizados. Esto siempre ha sido un problema. Mi regla de oro: cuanto más necesite trabajar para actualizar un comentario, más rápido será el comentario obsoleto.

Los comentarios XML son excelentes para el desarrollo de API. Funcionan muy bien con Intellisens y pueden hacer que generes un documento de ayuda HTML en muy poco tiempo.

Pero esto no es gratis: mantenerlos será difícil (mira cualquier ejemplo no trivial, entenderás lo que quiero decir), por lo que tenderán a ser obsoletos muy rápido. Como resultado, la revisión de Comentarios XML se debe agregar a su revisión de código como una verificación obligatoria y esta verificación se debe realizar cada vez que se actualice un archivo.

Bueno, dado que es costoso de mantener, dado que una gran cantidad de símbolos no privados (en desarrollo no API) son usados solo por 1 o 2 clases, y dado que estos símbolos a menudo se explican por sí mismos, nunca aplicaré una regla que diga que cada símbolo no privado debe ser XML comentado. Esto sería excesivo y contraproducente . Lo que obtendrá es lo que vi en muchos lugares: Comentarios XML casi vacíos que no agregan nada al nombre del archivo simbólico. Y el código es un poco menos legible ...

Creo que la muy, muy importante línea de guía sobre comentarios en código normal (que no es API) no debe referirse a CÓMO se deben escribir, sino a QUÉ deberían contener . Muchos desarrolladores aún no saben qué escribir. Una descripción de lo que debería comentarse, con ejemplos, sería mejor para su código que simplemente una simple: "Utilice los comentarios XML en cada simbología no privada".