Perché i blocchi /// comment sono importanti?

Qualcuno una volta ha detto che dovremmo anteporre a tutti i nostri metodi i /// <summary>blocchi di commento (C #) ma non ha spiegato il perché.

Ho iniziato a usarli e ho scoperto che mi infastidivano un po ', quindi ho smesso di usarli ad eccezione delle librerie e dei metodi statici. Sono ingombranti e dimentico sempre di aggiornarli.

C'è qualche buon motivo per usare i /// <summary>blocchi di commenti nel tuo codice?

Di solito uso sempre //commenti, sono solo i /// <summary>blocchi che mi chiedevo.

Usali il più possibile.

Sì, quelli sono commenti speciali che diventano la documentazione per il metodo. I contenuti <summary>, i tag dei parametri, ecc. Che vengono generati vengono visualizzati in intellisense quando tu o qualcun altro si appresta a chiamare il metodo. Possono essenzialmente vedere tutta la documentazione per il tuo metodo o classe senza dover andare al file stesso per capire cosa fa (o provare a leggere la firma del metodo e sperare per il meglio).

Sì, usali assolutamente per tutto ciò che vuoi conservare o potrebbe essere condiviso.

Inoltre, usali insieme a Sandcastle e Sandcastle Help File Builder , che prende l'output XML e lo trasforma in una splendida documentazione in stile MSDN.

Nell'ultimo posto in cui ho lavorato, abbiamo ricostruito la documentazione ogni sera e l'ho ospitata come homepage interna. Le iniziali della società erano MF, quindi era MFDN;)

Normalmente però produco solo un file .chm, che può essere facilmente condiviso in giro.

Rimarrai sorpreso da quanto sei dipendente dalla documentazione di tutto una volta che inizi a vederlo in formato MSDN!

Se il tuo standard di codifica richiede che tu usi tali commenti (e uno standard di codifica per un'API o un framework potrebbe richiederlo), allora non hai scelta, devi usare tali commenti.

Altrimenti, considera seriamente di non utilizzare tali commenti. Puoi evitarli nella maggior parte dei casi modificando il codice in questo modo:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

per

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

per

    public bool IsAuthorizedToAccessResource( User user ) {

    }

La tua classe, metodo e denominazione delle proprietà dovrebbero essere evidenti, quindi se ne hai bisogno, probabilmente è un odore.

Tuttavia, consiglierei di usarli su qualsiasi classe pubblica, metodo e proprietà in un'API, in una libreria, ecc ... Come minimo, genereranno i documenti per aiutare qualsiasi sviluppatore a usarlo e ti impediranno di avere per scriverli.

Ma comunque lo tagli, lo mantieni o li elimini.

Se scopri che devi continuare a tornare indietro e modificare i tuoi commenti in modo che corrispondano al nuovo codice, in primo luogo potresti sbagliare. L'elemento di riepilogo dovrebbe contenere esattamente questo - un riepilogo - il cosa e il perché della cosa che stai riassumendo.

Descrivere come funziona qualcosa nei commenti viola DRY. Se il tuo codice non è abbastanza auto-descrittivo, forse dovresti tornare indietro e refactoring.

Sì, li ho creati. [quando si creano nuovi sistemi da zero]

No, non ne ho mai beneficiato. [quando si lavora su sistemi esistenti che necessitavano di manutenzione]

Ho scoperto che i commenti "Riepilogo" alla fine tendono a non essere sincronizzati con il codice. E una volta che ho notato alcuni commenti che si comportano male, tendo a perdere fiducia in tutti i commenti su quel progetto - non sei mai sicuro di quali fidarti.

Dimenticare di fare qualcosa non lo rende una cattiva idea. Dimenticare di aggiornare qualsiasi documentazione è. Li ho trovati molto utili nella mia programmazione e le persone che ereditano il mio codice sono grate di averli.

È uno dei modi più visibili per documentare il tuo codice.

È una seccatura dover trovare il codice sorgente per leggere la documentazione in linea o scavare un documento che ripercorre quello che fa il codice. Se riesci a far apparire qualcosa di utile attraverso l'intelligenza, allora le persone ti adoreranno.

" Deve essere usato moltissimo, come me;) "

Giocavo con i commenti (///). Per una lezione puoi semplicemente fare un commento come questo

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Ma, per un metodo, puoi aggiungere altro con la descrizione di parametri e tipi di ritorno.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Puoi usare una scorciatoia per creare questo commento (///+Tab).

usandoli ad eccezione delle biblioteche

Questo è il momento in cui sono utili. Con la generazione della documentazione XML attivata e un riferimento all'assembly, senza il suo progetto, mostrerà maggiori dettagli in intellisense.

Ma per gli interni del progetto attuale, si intromettono.

Li uso, ma come altre persone hanno detto non universalmente. Per i metodi piccoli possono essere facilmente più grandi del codice che stanno spiegando. Sono molto utili per generare documentazione che può essere fornita a persone nuove al sistema in modo che abbiano qualcosa a cui fare riferimento durante l'apprendimento. Anche se, come programmatori, di solito possiamo scovare qual è il codice perché è bello avere i commenti per guidarci e agire come una stampella. Se deve essere annotato da qualche parte, nel codice è il punto in cui è più probabile che rimanga aggiornato (più probabilmente di un documento Word fluttuante).

Uso l'equivalente in VB (dal momento che non mi permettono di usare C # - apparentemente è troppo difficile ... nessun commento.) Li trovo molto convenienti. Il più delle volte aspetto che la procedura o la funzione siano praticamente completate prima di inserirli, anche solo per evitare di dover modificare i commenti o di averli "fuori sincrono".

Non scrivo necessariamente un romanzo - solo le basi, la descrizione del parametro e alcune osservazioni (di solito quando c'è qualcosa di "fuori dall'ordinario" in corso lì dentro) - soluzione alternativa o altra merda che preferirei non avere lì ma nessuna scelta "per ora".) (Sì, lo so, "per ora" può durare anni.)

Sono gravemente irritato dal codice non commentato. Un consulente ha scritto la versione iniziale di uno dei nostri componenti e non ha commentato nulla e la sua scelta di nomi lascia a desiderare qua e là. È passato più di un anno e stiamo ancora sistemando le sue cose (oltre a lavorare sulle nostre cose).