Commenti XML C#: quanti riferimenti <see ... /> nei commenti XML sono utili?

Question

Nella nostra azienda scriviamo commenti Xml eccessivi. Un metodo tipico è deve essere documentata in questo modo:

/// <summary> 
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> 
/// <returns> 
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. 
/// </returns> 
bool Contains(ISchedule schedule); 

/// <summary> 
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> 
/// from this <see cref="IScheduler"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> 
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> 
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> 
void Remove(ISchedule schedule); 

Come si può vedere quasi ogni nome che è possibile fare riferimento utilizzando un tag <see cref>.
Lo trovo troppo. La maggior parte dei nostri file di codice sono così saltati fuori con tali commenti. Rende la sezione dei commenti quasi illeggibile.

Cosa ne pensi? Ti piace questo tipo di documentazione nel codice o no?

Come al solito penso che non ci sia una risposta in bianco e nero a un tale tipo di domanda, è per questo che l'ho fatto wiki.

MODIFICA:
La mia domanda non era se i tag see-ref stessi sono utili per impostazione predefinita. È chiaro che i collegamenti generati nel file .chm (o qualsiasi altro tipo di documento generato) sono molto utili. La mia domanda era se fosse davvero utile taggare ogni occorrenza di ogni sostantivo "linkabile" nei commenti.
Usiamo Sandcastle per generare il docu ogni notte. Sfortunatamente è usato raramente da altri sviluppatori, ma questo è un altro problema.

Answer 1

Il punto di tutti è che quando qualcosa come Sandcastle viene utilizzato per generare documenti HTML o CHM per la libreria, tali documenti ottengono la navigazione ipertestuale tra gli oggetti. Quindi la domanda è: quando usi MSDN, trovi utile poter fare clic su un nome di classe, farlo navigare verso l'aiuto per quella classe, o stai bene copiandolo e incollandolo nel campo di ricerca?

Sì, aumenta il numero di codice (anche se i commenti possono essere compressi), ma se spedisci effettivamente la documentazione ad altri, è dannatamente utile.

Answer 2

C'è un motivo particolare per questo tipo di commenti: possono essere utilizzati per generare documentazione o per aggiungere informazioni aggiuntive al completamento automatico. Sono d'accordo sul fatto che siano eccessivamente prolissi e difficili da leggere per la maggior parte delle situazioni, ma sono utili per aggiungere all'interfaccia che si esporrà esternamente.

Si consiglia di utilizzare un editor che consente di attivare e disattivare i commenti.

Alcune lingue consentono di memorizzare commenti come metadati su variabili e funzioni, che è una buona alternativa.

Answer 3

Personalmente, penso che quello che hai sia un po 'esagerato.

Lo scopo dei riferimenti "vedere" è quello di fornire un buon collegamento tra gli argomenti nella documentazione della guida generata dopo l'analisi.

Nel tuo caso, le librerie specifiche di business fanno riferimento gli elementi linguistici, vale a dire:

<see langword="true"/> 

Personalmente ritengo che collegamenti ipertestuali ad altri oggetti correlati nella libreria è una caratteristica molto utile. Rende la lettura dell'aiuto molto più utilizzabile per i tuoi utenti.

I collegamenti ipertestuali agli elementi del linguaggio sono qualcosa che ritengo dovrebbero esistere solo all'interno della guida del linguaggio stesso. Nel caso di una libreria di terze parti, questo "confonde" il messaggio mettendo link ovunque. Questo rende i buoni link meno efficaci, dal momento che vengono nascosti nel caos.

Vorrei suggerire un uso liberale del collegamento alle classi correlate nella libreria. Eviterei di aggiungere collegamenti ipertestuali alle classi della libreria di base, tranne in casi specifici in cui è particolarmente utile per qualche motivo (raro). Il collegamento a "true" e "IDisposable.Dispose", ecc., Non aggiunge molto valore.

Fidati del tuo utente per capire il framework di base, ma insegnagli la tua biblioteca.

Answer 4

Come detto ctacke, è molto utile per il collegamento ipertestuale. Tuttavia, se non si sta effettivamente spedendo la documentazione, tutta la codifica rende la documentazione praticamente impossibile da leggere. In tal caso, la documentazione è per lo sviluppatore (modifica: INTERNAL) e se non è in grado di leggerlo, stai perdendo tempo.

Come regola generale, tendo al primo riferimento a un tipo o membro e lasciando il resto non collegato. Lascia i commenti abbastanza puliti e fornisce ancora collegamenti significativi.

Answer 5

Quando si lavora con Visual Studio, è possibile utilizzare il plug-in CR_Documentor (è gratuito, è possibile ottenerlo here) per la lettura/scrittura dei commenti WYSiWYG. Sembra che sia stato generato un aiuto per Sandcastle o NDoc, ma è stato reso al volo. È davvero utile e non devi preoccuparti dei commenti xml non elaborati.