Aggiunta di descrizioni di classe al codice?

Question

Sto finendo un progetto a cui sto lavorando da un po 'e sto solo facendo gli ultimi ritocchi.

Una cosa che vorrei fare è aggiungere descrizioni di classe nella parte superiore di ogni file di classe (per aiutare me stesso e altri programmatori a capire cosa sta succedendo). Il mio pensiero è di usare solo un po 'di "/" per staccare una sezione per scrivere qualche nota, ma forse c'è un modo migliore? C'è un modo per farlo in Visual Studio?

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

Answer 1

Sì, si dovrebbe usare il normale XML documentation:

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

In questo modo apparirà nella Intellisense, e se si crea la documentazione con Sandcastle/NDoc/Doxygen etc apparirà in modo appropriato.

Se si digita "///" nella riga sopra la classe, si dovrebbe vedere un modello appropriato per iniziare. Vedere il link MSDN sopra per ulteriori informazioni.

Answer 2

Uso XML documentation comments:

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

Quando si digita il tre barre di Visual Studio vi aiuterà con il resto.

Non utilizzare la formattazione ASCII di fantasia perché quando si refactoring per modificare i nomi di classe si spenderà anni riformattando tutte le vostre caselle per farli allineare nuovamente piacevolmente.

Answer 3

I commenti della documentazione XML descritti nelle risposte precedenti sono la strada da percorrere per la documentazione delle classi e dei metodi.

Se sono necessarie informazioni aggiuntive in ciascun file per testo non di documentazione, come data di creazione, crediti, messaggi di copyright e così via, è possibile aggiungerlo come snippet o aggiungerlo al modello di Visual Studio appropriato. VS ha variabili speciali per modelli come $ username $ e $ time $ che può essere utilizzato per inserire automaticamente questi valori ogni volta che aggiungi un nuovo elemento in base al modello.