Quali sono le virtù di utilizzare i commenti XML in .NET?

Question

non riesco a capire le virtù dell'utilizzo di commenti XML. So che possono essere convertiti in documentazione bello esterno al codice, ma lo stesso può essere raggiunto con la sintassi Doxygen molto più conciso. A mio parere i commenti XML sono sbagliato, perché:

1. Si offuscare i commenti e il codice in generale. (Sono più difficili da leggere da esseri umani).
2. Meno codice può essere visualizzato su un unico schermo, perché "Riepilogo" e "/ sintesi" prendono le linee aggiuntive.
3. (rimosso)

Che poi avrebbe potuto essere i motivi, per cui XML è stato preferito nel .NET piuttosto che la sintassi semplice Doxygen?

Answer 1

Non è in realtà una risposta corretta qui imo. Nessuno dei due sistemi è "migliore" rispetto agli altri, in realtà -. Entrambi fanno lo stesso lavoro, alla fine, che è consentono di generare la documentazione del codice

Il risultato finale può essere formattato esattamente nello stesso modo per ciascuno di essi, e hanno più o meno le stesse funzionalità in termini di ciò etichette ecc sostengono, per cui il suo veramente basso per scelta personale qui.

Personalmente trovo commenti XML per essere molto più leggibile, molto più logico e semplicemente facile da usare - ma che è con il vantaggio aggiunto di avere Visual Studio genera automaticamente stub per me è sufficiente compilare, e il supporto eccellente ha per crollare loro in modo che non occupano un sacco di spazio sullo schermo. Sono sicuro che qualcuno che proviene da una modifica di fondo nel VI o some_other_IDE avrà un'opinione diversa, ma non v'è alcun reale vantaggio per entrambi.

Quindi direi che in realtà dipende da quello IDE che si sta utilizzando e che cosa e il vostro team sono abituati ad usare.

Ora, se ti stai chiedendo il motivo per cui Microsoft ha scelto di integrare così strettamente con XML commentando all'interno di Visual Studio, che è una questione diversa. Molto probabilmente è a causa di fatti che: sarebbe più semplice per loro trasposizione entro VS (in quanto possono riutilizzare codice esistente per generare / leggere i commenti e costruire IntelliSense, ecc), hanno una tendenza per attaccare a "norme "in ogni caso (sia esso il proprio o di settore quelle), e anche di licenza motivi come detto da Jeff.

solo aggiungere che il prodotto Microsoft sta usando all'interno di VS si chiama "Sandcastle", che è uno strumento XML generazione doc in-house. Essa ha la sua pagina wiki @ http://docproject.codeplex.com/Wikipage

Answer 2

1. Le scelte IDE su per le osservazioni e li mostra quando si utilizza questo metodo.
2. Tutti coloro che hanno programmi di C # è probabilmente familiarità con il sistema di commenti XML. C'è meno da imparare per un nuovo noleggio.

Non sto dicendo che Doxygen non meglio è, è solo che il sistema di commento XML è più familiare a tutti, e che va un lungo cammino. E 'solo una cosa in meno si deve addestrare un nuovo noleggio da fare.

Per quanto riguarda le variabili lasciando senza commenti. Che cosa può essere evidente a voi, non sarà a qualcun altro (o per voi 6 mesi dopo).

Ok ora mi sembra di vedere quello che chiedete.

1. commenti offuscando. La codifica dei colori aiuta. Personalmente, la scansione rapidamente oltre il testo grigio e solo leggere ciò che è verde a meno che non ho bisogno di leggere il testo XML. (Nelle mie impostazioni almeno).

2. Abbiamo monitor di grandi dimensioni in modo da ottenere più codice sullo schermo in generale. (E 'più conveniente acquistare un monitor di grandi dimensioni che alle persone riqualificare in generale). L'altra cosa su questo troppo, è che scommetto che stai solo attivamente alla ricerca di una funzione alla volta, quindi se questo si adatta interi di funzione su una pagina, probabilmente non sono soffrendo troppo da non vedere più codice. Ora, se le funzioni sono lunghe, quindi ho potuto vedere che essere un problema.

3. Abbiamo messo i commenti di sintesi su una sola riga, quando possibile (ammesso che non è davvero grande). Che riduce la spazio utilizzato.

4. Non so se doxygen fa questo, ma è possibile comprimere i commenti in modo che siano fuori strada.

Answer 3

Il processo primario di documentazione XML è non per generare la documentazione. E 'quello di fornire buone informazioni IntelliSense per il cliente della classe. Spedire il file XML generato con la vostra assemblea.

Answer 4

Le virtù di utilizzare i commenti XML in .NET

Sono supportate nativamente dal compilatore C # e Visual Studio, che fornisce un unico luogo per documentare l'API per l'uso in forma cartacea, on-line, e la documentazione intellisense.

Questo articolo della rivista MSDN afferma quanto segue:

  

In ogni progetto, c'è qualcuno che   non è felice con la documentazione.   I conduttori del team vogliono altri commenti in   la fonte, scrittori tecnici vogliono   maggiori informazioni scritte sulla   Il disegno di codice, la garanzia della qualità vuole   per vedere le specifiche funzionali, e   presto. Se tutti questi documenti sono   effettivamente scritto, avete ancora la   battaglia di mantenere tutti loro   sincronizzato.

Anche se il formato non è necessariamente l'ideale, commenti di documentazione XML forniscono una ricca sintassi in modo che questo può essere realizzato.

Perché non sostenere Doxygen in C #, invece?

Per quanto riguarda il motivo per cui il sistema XML esistente è stato scelto nel corso doxygen, avrei il sospetto che questo è soprattutto perché doxygen è rilasciato sotto GPL che significherebbe Visual Studio e il compilatore C # sarebbe anche bisogno per essere rilasciato in quanto tale - qualcosa che Microsoft sarebbe senza dubbio non vogliono fare considerando le termini della licenza GPL .

Answer 5

quello che trovo ancora più pazzesco è la popolarità del GhostDoc plugin. Se è possibile generare automaticamente un commento sulla base di un nome di metodo, perché hanno il commento a tutti?

Steve Yegge dice che sopra commentando è il segno di un programmatore principiante, ho un momento difficile in disaccordo con lui.

Answer 6

non sono di usarli nei vostri progetti.

Sono a di serie che sembra essere integrato in Visual Studio e se si utilizza StyleCop possono essere applicate. Quindi questa è la virtù qui.

Tuttavia, se si decide che si desidera utilizzare Doxygen allora non c'è nulla ti impedisce. Basta fare in modo sono coerenti.