Agregar descripciones de clase al código?

Question

Estoy terminando un proyecto en el que he estado trabajando por un tiempo, y estoy dando los últimos toques.

Una cosa que me gustaría hacer es agregar descripciones de clase en la parte superior de cada archivo de clase (para ayudarme a mí y a otros programadores a descubrir qué está pasando). Mi idea es usar un montón de '/' 'para encuadernar una sección para que escriba algunas notas, pero ¿tal vez hay una mejor manera? ¿Existe una forma integrada de hacerlo en Visual Studio?

///////////////////////////////////////////////////// 
//             // 
// KillZombies.cs         // 
//             // 
// Description: This class contains blah blah blah // 
//             // 
///////////////////////////////////////////////////// 

Answer 1

Sí, usted debe usar la normalidad XML documentation:

/// <summary> 
/// Describe your class quickly here. 
/// </summary> 
/// <remarks> 
/// Add more details here. 
/// </remarks> 

De esa manera se mostrará en Intellisense, y si usted construye su documentación con castillos de arena/ndoc/Doxygen etc que aparecerá de manera apropiada.

Si escribe "///" en la línea sobre su clase, debería ver una plantilla adecuada para comenzar. Vea el enlace MSDN arriba para más información.

Answer 2

Uso XML documentation comments:

/// <summary> 
/// This class performs an important function. 
/// </summary> 

Al escribir el tres barras de Visual Studio le ayudará con el resto.

No utilice el elegante formato ASCII porque cuando refactorice para cambiar los nombres de las clases, pasará años formateando todas sus cajas para que se alineen de nuevo.

Answer 3

Los comentarios de la documentación XML descritos en las respuestas anteriores son el camino a seguir para la documentación de clases y métodos.

Si necesita información adicional en cada archivo para el texto que no es de documentación, como fecha de creación, créditos, mensajes de copyright, etc., podría agregarlo como fragmento o agregarlo a la plantilla de Visual Studio adecuada. VS tiene variables especiales para plantillas como $ username $ y $ time $ que se pueden utilizar para insertar automáticamente estos valores cada vez que agrega un nuevo artículo basado en su plantilla.