Suggerimenti per i commenti XML per la programmazione in C# [chiuso]

Question

Buongiorno, pomeriggio, sera o notte (a seconda del fuso orario).

Questa è solo una domanda generale sui commenti XML in C#.Non sono mai stato molto bravo nel commentare i miei programmi, sono sempre stato più un nome verboso di variabili/proprietà/metodi e ho lasciato che il codice parlasse da solo.Scrivo commenti se sto codificando qualcosa che crea abbastanza confusione, ma per la maggior parte non scrivo molti commenti.

Stavo leggendo alcuni commenti XML in .NET, Sandcastle e il generatore di file di aiuto su codeplex e questo mi ha portato sulla strada di voler documentare il mio codice e generare documentazione carina e utile per coloro che devono approfondire il mio codice quando non sarò più qui.

La mia domanda riguarda gli standard e le convenzioni.Esiste una guida per commentare XML "buoni"?Dovresti commentare OGNI variabile e proprietà?OGNI metodo?Fondamentalmente sto solo cercando suggerimenti su come scrivere buoni commenti che verranno compilati da Sandcastle in una buona documentazione in modo che altri programmatori non malediscano il mio nome quando finiscono per dover lavorare sul mio codice.

Grazie in anticipo per i tuoi consigli e suggerimenti, Scott Vercuski

Answer 1

Personalmente, ci assicuriamo che ogni metodo pubblico e protetto ha commenti XML. Inoltre vi fornirà Intellisense, e non solo degli utenti finali documentazione di aiuto. In passato, abbiamo anche incluso su dichiarazioni di ambito privato, ma non lo sento è al 100% richiesto, fino a quando i metodi sono brevi e on-point.

Non dimenticate che ci sono gli strumenti per farvi XML compiti commentando facile:

• GhostDoc -. Commento eredità e di template aggiuntivo
• Sandcastle File della guida Builder - Consente di modificare i progetti Sandcastle tramite una GUI, può essere eseguito da una riga di comando (per l'automazione di costruzione), e può modificare MAML per gli argomenti della Guida non derivate dal codice. (La versione 1.8.0.0 alpha è molto stabile e molto migliorata. Sono state usando per circa un mese, nel corso 1.7.0.0)

Answer 2

I commenti sono molto spesso obsoleti.Questo è sempre stato un problema.La mia regola pratica:più devi lavorare per aggiornare un commento, più velocemente quel commento diventerà obsoleto.

I commenti XML sono ottimi per lo sviluppo di API.Funzionano abbastanza bene con Intellisens e possono farti generare un documento di aiuto HTML in pochissimo tempo.

Ma questo non è gratuito:mantenerli sarà difficile (guarda qualsiasi esempio non banale, capirai cosa intendo), quindi tenderanno a diventare obsoleti molto velocemente.Di conseguenza, revisione XML I commenti dovrebbero essere aggiunti alla revisione del codice come controllo obbligatorio e questo controllo dovrebbe essere eseguito ogni volta che un file viene aggiornato.

Bene, poiché è costoso da mantenere, poiché molti simboli non privati ​​(nello sviluppo non API) sono utilizzati solo da 1 o 2 classi, e poiché questi simboli sono spesso autoesplicativi, non imporrei mai una regola che lo dica ogni simbolo non privato dovrebbe essere commentato XML. Ciò sarebbe eccessivo e controproducente.Quello che otterrai è quello che ho visto in molti posti:Commenti XML quasi vuoti che non aggiungono nulla al nome del simbolo.E il codice è solo un po' meno leggibile...

Penso che il molto molto un'importante linea guida sui commenti nel codice normale (non API) non dovrebbe riguardare COME dovrebbero essere scritti ma circa COSA dovrebbero contenere.Molti sviluppatori ancora non lo sanno Che cosa scrivere.Una descrizione di ciò che dovrebbe essere commentato, con esempi, farebbe meglio per il tuo codice piuttosto che un semplice:"Utilizzare commenti XML su ogni simbolo non privato.".

Answer 3

Documento le classi pubbliche e i membri pubblici/protetti di tali classi.

Non documento i membri privati ​​o interni o le classi interne.Quindi variabili (penso che tu intenda campi) perché sono private.

L'obiettivo è creare documentazione per uno sviluppatore che non ha accesso immediato al codice sorgente.

Cercare di inserire alcuni esempi in cui l'utilizzo non è ovvio.

Answer 4

I molto raramente commentare variabili di metodo, e altrettanto raramente (non esisto in quanto sono di solito coperti da una proprietà, o semplicemente se utilizzando le proprietà auto-implementato) campi.

In generale Mi sforzo per aggiungere commenti significativi per tutti i membri pubblici / protette, che è a portata di mano, in quanto se si accendono i commenti XML durante la costruzione, si ottiene avvisi automatici per i commenti mancanti. A seconda della complessità, non potrei riempire ogni dettaglio - vale a dire se è ovvio al 100% ciò che ogni parametro ha da fare (cioè non v'è alcuna logica speciale, e c'è solo 1 modo logico di interpretare le variabili), poi i potrebbe ottenere pigro e non aggiungere commenti sui parametri.

Ma certamente cerco di descrivere ciò che i metodi, tipi, proprietà, ecc rappresentano / fare.

Answer 5

documentare il pubblico metodi / proprietà / etc sulle nostre librerie. Come parte del processo di generazione che usiamo NDoc per creare un riferimento Web MSDN-like. E 'stato molto utile per una rapida consultazione e ricerca.

E 'grande anche per Intellisense, soprattutto con i nuovi membri del team o, come hai detto tu, quando l'autore originale è andato.

Sono d'accordo che il codice, in generale, dovrebbe essere auto-esplicativo. Il documention XML, per me, è più su di riferimento e di ricerca, quando non si ha l'open source.

Answer 6

Personalmente il mio parere è quello di evitare di commentare. Commentando è pericoloso. Perché in settore abbiamo sempre aggiornare il codice (perché le esigenze di business e sono sempre in evoluzione), ma variano raramente che aggiorniamo i nostri commenti. Questo può sviare i programmatori.