Commenti XML: usare o non usare?

Question

I miei collaboratori raramente (se mai) usano i commenti XML quando lavorano sul nostro software (non posso dire di essere migliore). Di recente ho visto i vantaggi di usarli, ma ne vale davvero la pena se il codice che stanno documentando è scritto chiaramente (nomi di funzioni / variabili espressivi / descrittivi, alcuni commenti in linea)?

Grazie!

Answer 1

I commenti XML sono utili per generare documentazione. Se il codice è chiaramente scritto, non dovresti avere bisogno di commenti per aiutarti a capire il codice.

Tuttavia i commenti della documentazione sono utili per l'utente delle classi perché (dovrebbero) contenere una descrizione della funzionalità della classe o dei metodi, non una descrizione del codice.

Answer 2

Penso che i commenti sul codice siano molto importanti, specialmente sui metodi e le proprietà del pubblico. Le persone possono intendere bene quando dicono che il loro codice è descrittivo e forse lo è, ma pensa al nuovo ragazzo che lo guarda:

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

A meno che non capisca il contesto del metodo, potrebbe non capirne lo scopo. Il problema principale che le persone sembrano avere con i commenti è che non sono molto utili. Questo perché le persone scrivono commenti negativi. Dovresti parlare di ciò che sta succedendo e non di ciò che è. Vedo che questo metodo è un metodo di estrazione, quindi commenti come:

 <Summary>Extracts The Fumble <\Summary>

Sono uno spreco di energia. È meglio:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

Vedi la differenza?

Tendo a usare solo parametri sommari e ritorni poiché tutti mostrano in intellisense, tutto il resto gradisce le osservazioni e può essere una perdita di tempo in quanto non vengono sempre mostrati.

Quanto al ragazzo che rifiuta di aggiornare i suoi commenti dopo aver cambiato qualcosa. Le revisioni del codice dovrebbero essere utili. Personalmente uso commenti XML su metodi privati ??e ne sostengo due ma quello è una scelta personale. Sui metodi e le proprietà del pubblico? I non è facoltativo.

Answer 3

I commenti XML sono davvero utili per le API anche quelle utilizzate in un piccolo gruppo.

Answer 4

Lo troviamo utile, perché vs verifica automaticamente che ci siano determinati commenti. Inoltre, chiunque entri nell'organizzazione che ha usato vs prima sa come funzionano i commenti e non dobbiamo spiegare un nuovo sistema di codice per i commenti. A volte ne abbiamo generato la documentazione, ma in realtà è più semplice usarla perché riempie una serie di cose per te (come alcuni tag dei parametri, ecc.)

Answer 5

Per quanto riguarda il codice e i commenti interni, ecco un post di Jeffery Palermo che ho appena letto e con cui sono d'accordo.

In breve: molti commenti riducono solo la leggibilità e aiutano poco, buoni commenti possono essere molto utili ma aumentare i costi per la manutenzione del software e possono persino causare gravi problemi quando non vengono mantenuti e forniscono informazioni false. Non c'è sostituto per un codice ben progettato e nominato.

Answer 6

Non esiste un tag di annotazione che viene ignorato funzionalmente ma può essere elaborato da alcuni XSLT per essere trasformato direttamente in documentazione? I commenti sono buoni (e li uso), ma penso che il valore del tag di annotazione e la sua trasformazione diretta possano superare l'utilizzo del commento come documentazione. Quindi, in sintesi, usa i tag di annotazione per la documentazione che gli altri devono leggere, usa i commenti per le tue note o roba 'dietro le quinte' (ad esempio, 'OMG FIX QUESTO PRIMA DEGLI ESPLODI AL MONDO!')