Perché i blocchi di commenti /// sono importanti?

Use them as much as possible.

Sì, quelli sono commenti speciali che diventano la documentazione per il metodo. I contenuti di <summary> , i tag dei parametri, ecc. Che vengono generati vengono visualizzati in intellisense quando tu o qualcun altro ti stai preparando a chiamare il tuo 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 che potresti condividere.

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

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

Normalmente però produco solo un file .chm, che è facilmente condivisibile.

Saresti sorpreso di quanto dipendente possa arrivare a documentare tutto quando inizi a vederlo in formato MSDN!

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

Altrimenti, considera seriamente di non usare tali commenti. Nella maggior parte dei casi puoi evitarli modificando il tuo codice in questo modo:

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

    }

a

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

    }

a

    public bool IsAuthorizedToAccessResource( User user ) {

    }

La tua classe, metodo, & la denominazione delle proprietà dovrebbe essere evidente, quindi se ne avete bisogno, probabilmente è un odore.

Tuttavia, ti consiglio di utilizzarli su classi pubbliche, metodi e & proprietà in un'API, in una libreria, ecc. Per lo meno, genereranno i documenti per aiutare qualsiasi sviluppatore a utilizzarlo e impediranno di doverli scrivere.

Ma comunque lo dividi, mantienile o cancellale.

Se trovi che devi tornare indietro e modificare i tuoi commenti per corrispondere con il nuovo codice, potresti commetterli in errore. L'elemento di riepilogo dovrebbe contenere esattamente quello - un riassunto - il cosa e il perché della cosa che stai riepilogando.

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

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

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

Ho scoperto che i commenti di "Riepilogo" alla fine tendono a uscire dalla sincronizzazione con il codice. E una volta che ho notato alcuni commenti male comportanti, tendo a perdere la 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 è. Ho trovato questi molto utili nella mia programmazione e le persone che ereditano il mio codice sono grati di averli.

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

È un dolore dover trovare il codice sorgente per leggere la documentazione inline o scavare un documento su quello che fa il codice. Se riesci a far apparire qualcosa di utile attraverso l'intelligenza, la gente ti amerà.

"It has to be Used Very much, like me ;)"

Ero solito giocare con i commenti (///). Per un corso puoi semplicemente fare un commento come questo

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

Tuttavia, 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) .

using them except for libraries

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

Ma per gli interni del progetto attuale, si intromettono.

Li uso, ma come hanno detto altre persone non universalmente. Per piccoli metodi possono essere facilmente più grandi del codice che stanno spiegando. Sono molto utili per generare documentazione che possa essere data a persone nuove al sistema in modo che abbiano qualcosa a cui riferirsi mentre imparano. Anche se, come programmatori, di solito possiamo scoprire cosa sia un codice, è bello avere i commenti che ci guidano e fungono da stampella. Se ha da scrivere da qualche parte, allora nel codice è il posto dove è più probabile che si aggiorni (più probabilmente di un documento Word che gira intorno).

Uso l'equivalente in VB (dal momento che non mi permettono di usare C # - apparentemente è troppo difficile ... nessun commento.) Li trovo molto convenienti. La maggior parte delle volte aspetto che la procedura o la funzione siano completate in modo completo prima di inserirle, se non altro per evitare di dover modificare i commenti o di "non sincronizzarli".

Non scrivo necessariamente un romanzo - solo le basi, la descrizione dei parametri e alcune osservazioni (di solito quando c'è qualcosa di "fuori dall'ordinario" che sta succedendo lì - soluzione o altra schifezza che preferirei non avere in lì, ma non hanno scelta "per ora".) (Sì, lo so, che "per ora" può durare anni.)

Sono seriamente 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 qui e là. Ha passato più di un anno e stiamo ancora sistemando le sue cose (oltre a lavorare sulle nostre cose).