Voglio ricevere consigli ed esperienze su come scrivere commenti nel tuo codice. Come li scrivi nel modo più semplice e informativo? Quali sono le tue abitudini nel commentare parti di codice? Forse alcuni consigli esotici?

Spero che questa domanda raccolga i consigli e le raccomandazioni più interessanti per il commento, qualcosa di utile da cui tutti possono imparare.

OK, inizierò.

1. Di solito, non uso i /* */commenti anche quando devo commentare molte righe.

   Vantaggi : il codice appare visivamente migliore rispetto a quando si mescola tale sintassi con commenti di una riga. La maggior parte degli IDE ha la possibilità di commentare il testo selezionato e di solito lo fa con una sintassi di una riga.

   Svantaggi : difficile modificare tale codice senza IDE.

2. Inserisci "punto" alla fine di ogni commento finito.

   Per esempio:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Vantaggi : inserisci "punto" solo nei commenti che hai finito. A volte puoi scrivere informazioni temporali, quindi la mancanza di "punto" ti dirà che volevi tornare e aggiungere del testo aggiuntivo a questo commento.

3. Allinea il testo nelle enumerazioni, nei parametri di commento ecc.

   Per esempio:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Vantaggi : solo un aspetto migliore e visivamente più facile da trovare ciò di cui hai bisogno.

   Svantaggi : spendere tempo per allineare e più difficile da modificare.

4. Scrivi un testo nei commenti che non puoi ottenere analizzando il codice.

   Ad esempio, stupido commento:

   //Apply style.
   Apply(style);
   

   Vantaggi : avrai un codice chiaro e di piccole dimensioni con solo informazioni utili nei commenti.

Alcune delle affermazioni che seguono sono piuttosto personali, anche se con qualche giustificazione, e intendono essere così.

Tipi di commento

Per la breve versione ... Uso i commenti per:

• commenti finali che spiegano i campi nelle strutture di dati (a parte quelli, non uso davvero i commenti a riga singola)
• commenti multilinea eccezionali o orientati allo scopo sopra i blocchi
• documentazione per utente pubblico e / o sviluppatore generata dalla fonte

Leggi sotto per i dettagli e (forse oscuri) motivi.

Commenti finali

A seconda della lingua, utilizzando commenti a riga singola o commenti a più righe. Perché dipende È solo un problema di standardizzazione. Quando scrivo codice C, preferisco il codice ANSI C89 vecchio stile per impostazione predefinita, quindi preferisco averlo sempre /* comments */.

Pertanto, lo vorrei in C per la maggior parte del tempo, e talvolta (dipende dallo stile della base di codice) per le lingue con una sintassi simile al C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs è simpatico e lo fa con me M-;.

Se il linguaggio supporta i commenti a riga singola e non è basato su C, sarò più chiuso per utilizzare i commenti a riga singola. Altrimenti, temo di aver preso l'abitudine. Il che non è necessariamente negativo, in quanto mi costringe a essere conciso.

Commenti su più righe

Non sono d'accordo con il tuo precetto usando i commenti a riga singola per questo è visivamente più attraente. Io lo uso questo:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

O questo (ma non lo faccio più spesso, tranne che su una base di codice personale o principalmente per le comunicazioni sul copyright - questo è storico per me e proviene dal mio background educativo. Sfortunatamente, la maggior parte degli IDE si rovina quando si utilizza il formato automatico) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Se fosse davvero necessario, allora commenterei in linea usando ciò che ho menzionato in precedenza per i commenti finali, se ha senso usarlo in una posizione finale. In un caso di restituzione molto speciale, ad esempio, o per documentare switchle casedichiarazioni di una (raro, non uso switch spesso) o quando documento i rami in un if ... elseflusso di controllo. Se questo non è uno di questi, di solito un blocco di commenti al di fuori dell'ambito che delinea i passaggi della funzione / metodo / blocco ha più senso per me.

Li uso molto eccezionalmente, tranne se per la codifica in una lingua senza supporto per i commenti della documentazione (vedi sotto); nel qual caso diventano più diffusi. Ma nel caso generale, è davvero solo per documentare cose che sono destinate ad altri sviluppatori e sono commenti interni che devono davvero distinguersi. Ad esempio, per documentare un blocco vuoto obbligatorio come un blocco "forzato" catch:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Il che è già brutto per me, ma lo tollererei in alcune circostanze.

Commenti sulla documentazione

Javadoc e al.

Di solito li userei su metodi e classi per documentare le versioni che introducono una funzione (o la cambiano) soprattutto se si tratta di un'API pubblica e per fornire alcuni esempi (con chiari casi di input e output e casi speciali). Sebbene in alcuni casi un caso unitario possa essere migliore per documentarli, i test unitari non sono necessariamente leggibili dall'uomo (non importa quale DSL-cosa usi).

Mi disturbano un po 'per documentare campi / proprietà, poiché preferisco i commenti finali per questo e non tutti i framework di generazione di documentazione supportano i commenti finali della documentazione. Doxygen lo fa, ad esempio, ma JavaDoc no, il che significa che hai bisogno di un commento in alto per tutti i tuoi campi. Tuttavia, posso sopravvivere, dato che le linee Java sono relativamente lunghe la maggior parte delle volte, quindi un commento finale mi spaventerebbe ugualmente estendendo la linea oltre la mia soglia di tolleranza. Se Javadoc avesse mai preso in considerazione l'idea di migliorarlo, sarei comunque molto più felice.

Codice commentato

Uso una riga singola per un solo motivo, in linguaggi simili al C (tranne che per la compilazione del C rigoroso, dove non li uso davvero): commentare le cose durante la codifica. La maggior parte degli IDE dovrà attivare o disattivare i commenti a riga singola (allineati sul rientro o sulla colonna 0), e questo si adatta a questo caso d'uso per me. L'uso della commutazione per i commenti su più righe (o la selezione a metà riga, per alcuni IDE) renderà più difficile il passaggio tra commenti / commenti.

Ma poiché sono contrario al codice commentato in SCM, di solito è di breve durata perché eliminerò blocchi commentati prima di impegnarmi. (Leggi la mia risposta a questa domanda su "commenti in linea e SCM modificati" )

Stili di commento

Di solito tendo a scrivere:

• frasi complete con grammatica corretta (inclusa la punteggiatura) per i commenti della documentazione, poiché dovrebbero essere lette in seguito in un documento API o anche come parte di un manuale generato.
• ben formattato ma più impreciso su punteggiatura / maiuscole per blocchi di commenti su più righe
• blocchi finali senza punteggiatura (a causa dello spazio e di solito perché il commento è breve, che si legge più come un'istruzione tra parentesi)

Una nota sulla programmazione alfabetica

Potresti voler interessarti alla programmazione letterata , come introdotto in questo documento di Donald Knuth .

Il paradigma della programmazione alfabetica, [...] rappresenta un allontanamento dalla scrittura di programmi nel modo e nell'ordine imposti dal computer, e consente invece ai programmatori di sviluppare programmi nell'ordine richiesto dalla logica e dal flusso dei loro pensieri. 2 I programmi letterati sono scritti come un'esposizione ininterrotta della logica in un linguaggio umano ordinario, proprio come il testo di un saggio [...].

Gli strumenti di programmazione alfabetica vengono utilizzati per ottenere due rappresentazioni da un file sorgente letterato: uno adatto per l'ulteriore compilazione o esecuzione da parte di un computer, il codice "aggrovigliato" e un altro per la visualizzazione come documentazione formattata, che si dice sia "intessuta" dal fonte alfabetizzata.

Come nota a margine ed esempio: il framework JavaScript underscore.js , nonostante la non conformità con il mio stile di commento, è un ottimo esempio di una base di codice ben documentata e di una fonte annotata ben formata , sebbene forse non sia la migliore da usare come un riferimento API).

Queste sono convenzioni personali . Sì, potrei essere strano (e potresti esserlo anche tu). Va bene, purché tu segua e rispetti le convenzioni sul codice del tuo team quando lavori con colleghi, o non attacchi radicalmente le loro preferenze e convivi bene. Fa parte del tuo stile e dovresti trovare la linea sottile tra lo sviluppo di uno stile di codifica che ti definisce come un programmatore (o come un seguace di una scuola di pensiero o organizzazione con cui hai una connessione) e il rispetto della convenzione di un gruppo per coerenza .

Quando andavo all'università mi veniva sempre insegnato a commentare ogni riga di codice e ogni intestazione di metodo. È stato tamburato / indottrinato a tal punto da farlo senza dubbio. Dopo aver fatto parte di diversi team di sviluppo Agile in diverse società, posso dire che posso scrivere un commento una volta su una luna blu.

La ragione di ciò è duplice, prima di tutto non dovremmo più scrivere lunghi metodi monolitici che fanno 101 cose diverse, la classe, il metodo e i nomi delle variabili dovrebbero essere auto documentanti. Prendi il seguente metodo di accesso come esempio.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Questo può essere riscritto in qualcosa che è molto più leggibile e forse riutilizzabile:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Puoi vedere chiaramente dal metodo di accesso cosa sta succedendo. Potresti vederlo come un lavoro extra ma i tuoi metodi sono piccoli e hanno un solo lavoro. Inoltre, i nomi dei metodi sono descrittivi, quindi non è necessario scrivere alcun commento di intestazione del metodo. Se si finiscono con troppi metodi, questa è un'indicazione che i metodi correlati dovrebbero essere ricodificati in un altro oggetto come UserAuthenticationService, ricordare che un oggetto dovrebbe avere un solo lavoro.

In secondo luogo, ogni singolo pezzo di codice che scrivi, compresi i commenti, deve essere mantenuto, più commenti hai e più c'è da mantenere. Se rinomini una classe o una variabile, otterrai un errore di compilazione ma se cambi il modo in cui una sezione di codice funziona o la rimuovi e non aggiorni alcun commento correlato, non ci sarà alcun errore di compilazione e i commenti resteranno in sospeso causando confusione .

Se stai scrivendo un'API, credo che le interfacce, le classi e le enumerazioni rivolte al pubblico debbano avere commenti di intestazione ben scritti per la documentazione.

Concentrati meno sul formato e più sul contenuto. Ad esempio i commenti nel tuo esempio non mi dicono nulla di nuovo. Sono peggio che inutili in quanto riducono la lettura del codice e commenti come questi sono nella migliore delle ipotesi un vago riferimento a ciò che il programmatore originale pensava di fare nel momento in cui lo ha scritto. Vedo dall'esempio di codice che stai applicando uno stile "applica (Stile)", posso leggere la fonte. Non riesco a leggere la tua mente, perché lo stai facendo è ciò che il commento dovrebbe dirmi. ad es. anziché

//Apply style.

Apply(style);

dovrebbe essere

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

La maggior parte di noi lavora in team su codice esistente, formatta come il resto del team, nel modo in cui è già stato fatto. Coerenza molto più importante che carina.

Per quanto possibile, scrivi il tuo codice in modo che i commenti siano completamente estranei. Aggiungi commenti solo quando il codice non può essere scritto in modo tale da rendere evidente un concetto importante.

La mia preferenza è di mantenerlo davvero semplice. Evito ogni tipo di formattazione di fantasia. La ragione principale di ciò è che penso che il codice sorgente dovrebbe essere facilmente modificabile con anche l'editor di testo più semplice. Inoltre non ho mai avvolto duramente paragrafi di testo, ma invece ho lasciato che l'editor facesse il soft wrapping (senza aggiungere nuove righe).

Vedo spesso commenti del genere e alcuni strumenti lo generano automaticamente in questo modo:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Due righe in meno:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDE ed Editor, leggermente al di sopra del livello del blocco note, sono in grado di rilevare i commenti e stamparli in un colore diverso. Non è necessario decorare l'inizio della linea con gli asterix.

Si risparmiano anche alcuni byte, se si utilizza una scheda per il rientro.

Se non usi un editor sofisticato, che rende il commento in tono grigio, la grande quantità di asterix funzionerà come enfasi e attirerà la tua attenzione, che è l'opposto della cosa giusta da fare: rimanere indietro.

Ecco un "anti-pattern" che ho trovato in tutto il codice del mio lavoro: l'uso dei commenti come "registro delle modifiche"; ecco a cosa serve il registro nel tuo sistema di controllo versione. Il codice è disseminato di cose come:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

e di solito include spesso il vecchio codice che è stato commentato (di nuovo, questo è il punto di un sistema VCS, quindi non è necessario che sia inserito nel codice dopo la scrittura del nuovo codice). Anche qualcosa da evitare sono i commenti ripetuti come "Perché ne abbiamo bisogno?" o peggio ancora, "Questo dovrebbe probabilmente essere rinominato" (perché ci sono strumenti sofisticati per rinominare, quindi nel tempo impiegato per scrivere quel commento avresti potuto rinominare la cosa). Ancora una volta, mi occupo di entrambi questi commenti su base regolare, sulla falsariga di:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Scegli un sistema di documentazione come doxygen e seguilo . Continua a controllare i documenti prodotti.
2. Prova a immaginare qualcuno di nuovo nella base di codici che arriva e legge i tuoi documenti, potrebbero iniziare con questo? Gli stagisti sono in realtà buoni per questo, siedano a uno nuovo con la tua base di documenti esistente e un semplice compito e vedi fino a che punto arrivano, se inciampano, molto sicuro che tutto ciò che hai detto loro per farli andare di nuovo vada nei documenti.
3. Trasforma i commenti della documentazione in un punto di controllo nei tuoi processi di revisione.

I lettori di codice di solito cercano di rispondere a tre domande:

1. Cosa fa questa classe o funzione? Se è difficile rispondere, fa troppo. Il codice difficile da documentare di solito è semplicemente sbagliato.
2. Come lo uso? Un esempio può essere abbastanza buono.
3. Quel codice è sorprendente. Perchè lo hai fatto? Risposte molto probabilmente: aggirare un bug nei componenti di terze parti, perché l'ovvia tecnica si è rivelata troppo lenta

Tutto il resto dovrebbe essere espresso nel codice. Come scrivere in prosa, questa è un'arte e richiede molta pratica. L'unico modo per sapere se il tuo codice è comprensibile è convincere qualcun altro a leggerlo. Quando non capiscono qualcosa, non spiegarlo verbalmente. Migliora il codice. Aggiungi commenti come ultima risorsa.

Se vedo "doppia lunghezza" chiederò "Qual è l'unità di misura?" Non aggiungere un commento. Cambia il nome della variabile. Se vedo un blocco di codice e dico "cosa fa questo?", Non aggiungere un commento. Estrai una funzione con un nome significativo. Se non riesci a estrarre una funzione perché avrebbe bisogno di 17 argomenti, quindi refactoring il codice.