it-swarm.it

Perché i blocchi /// comment sono importanti?

Qualcuno una volta ha detto che dovremmo aggiungere tutti i nostri metodi al prefisso /// <summary> blocchi di commenti (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 /// <summary> blocchi di commenti nel tuo codice?

Di solito uso // commenti sempre, è solo il /// <summary> blocchi di cui mi chiedevo.

49
Rachel

sali il più possibile.

Sì, questi 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 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).

91
Ryan Hayes

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!

17
Tom Morgan

Se lo standard di codifica richiede l'utilizzo di tali commenti (e uno standard di codifica per un'API o un framework può richiederlo), allora non hai scelta, devi utilizzare 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 ) {

    }
12
azheglov

La denominazione di classe, metodo e proprietà dovrebbe essere evidente, 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 cancelli.

4
John MacIntyre

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 qualcosa funziona nei commenti viola il DRY. Se il tuo codice non è abbastanza auto-descrittivo, forse dovresti tornare indietro e refactoring.

2
Nobody

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.

1
Preets

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 cercare un documento che analizzi il codice. Se riesci a far apparire qualcosa di utile attraverso l'intelligenza, allora le persone ti adoreranno.

1
Abe Miessler

"Deve essere usato moltissimo, come me;)"

Giocavo 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
    {

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 utilizzare una scorciatoia per creare questo commento (///+Tab).

1
Sreekumar P

Uso l'equivalente in VB (poiché non mi permettono di usare C # - apparentemente è troppo difficile ... nessun commento.) Li trovo molto convenienti. La maggior parte del tempo aspetto fino la procedura o la funzione è praticamente completata prima di inserirli, anche solo per evitare di dover cambiare 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).

0
MetalMikester

usandoli ad eccezione delle biblioteche

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

Ma per gli interni del progetto attuale, si intromettono.

0
Richard

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 data 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ù probabile di un documento Word fluttuante).

0
Todd Williamson