Come trattare la tautologia nei commenti? [chiuso]

Nella maggior parte dei progetti su cui lavoro, non c'è una quantità significativa di tempo per scrivere commenti dettagliati su ogni singolo membro della classe.

Ciò non significa che non ci sia tempo per i commenti; al contrario, c'è un sacco di tempo per commenti tautologici che restituiscono una versione riformulata di ciò che viene commentato. Funzionano perfettamente come punto di partenza .

Soprattutto dato l'uso dei commenti di Visual Studio che accompagnano IntelliSense , è una buona idea iniziare con un po 'di informazioni su il campo:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Quindi, mentre continui a codificare, quando non riesci a ricordare se UpdateLocation era la posizione in cui si è verificato l'aggiornamento o la posizione in cui è stato inviato l'aggiornamento, si Dovrò rivisitare il codice. È a questo punto che dovresti aggiungere queste informazioni aggiuntive:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Se un altro programmatore ti chiede informazioni su un campo, aggiorna i commenti con tali informazioni:

What sort of update should Example.UpdateLocation be used to store?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Proprio come un programma ha dei bug, i buoni commenti hanno bug che devono essere elaborati iterativamente. Lo scopo dei commenti è di aiutare a capire il codice quando lo si rivisita sei mesi dopo e non si ricorda nulla del funzionamento del programma.

E proprio come la programmazione, i tuoi commenti devono iniziare da qualche parte. I commenti tautologici sono il Hello World! dei commenti, mentre ti eserciti a scrivere e ad aggiornare la documentazione, la tua documentazione di partenza diventerà sempre più resistente.

I commenti dovrebbero mai duplicare il tuo codice. I commenti non dovrebbero rispondere alla domanda " come? ", ma solo " perché? " e " cosa? ". Perché viene scelto un tale algoritmo, quali sono le ipotesi implicite qui (a meno che il tuo linguaggio non sia abbastanza potente da esprimerlo con il sistema dei tipi, i contratti e simili), qual è una ragione per fare questa cosa, ecc.

Consiglierei di dare un'occhiata alla pratica della programmazione letteraria per un'ispirazione.

I commenti dovrebbero descrivere il codice, non duplicarlo. Questo commento di intestazione si duplica. Lasciarlo fuori.

Lasciali fuori!

Normalmente, è buona prassi rimuovere i commenti laddove le informazioni espresse in essi siano già presenti altrove. Se puoi esprimere chiaramente e inequivocabilmente lo scopo di un metodo dandogli un buon nome allora c'è non c'è bisogno di un commento .

Inseriscili!

Il tuo esempio illustra due eccezioni a questa regola:

In primo luogo, "UpdateLocation" può essere ambigua (a seconda del contesto). In tal caso, è necessario fornire un nome migliore o fornire un commento per rimuovere l'ambiguità. Migliorare il nome è generalmente l'opzione migliore, ma questo non è sempre possibile (quando si implementa un'API pubblicata, ad esempio).

In secondo luogo, "///" in C # indica un commento destinato a essere utilizzato per generare automaticamente la documentazione. L'IDE utilizza questi commenti ai suggerimenti degli strumenti, e ci sono strumenti (Sandcastle) che possono generare file di aiuto e così via da questi commenti. Come tale, ci sono argomenti per inserire questi commenti anche se i metodi che documentano hanno già nomi descrittivi. Anche allora, tuttavia, molti sviluppatori esperti potrebbero disapprovare la duplicazione delle informazioni. Il fattore decisivo dovrebbe essere il bisogno di coloro per i quali è prevista la documentazione.

Non sono assolutamente d'accordo con le risposte "non scrivere commenti". Perché? Permettetemi di sottolineare cambiando un po 'il vostro esempio.

public Uri UpdateLocation ();

Quindi cosa fa questa funzione:

• Restituisce il "luogo dell'aggiornamento"? o
• "aggiorna" la posizione e restituisce la nuova posizione?

Puoi vedere che senza un commento c'è ambiguità. Un nuovo arrivato può facilmente commettere l'errore.

Nel tuo esempio, è una proprietà, quindi i metodi "ottieni / imposta" rivelano che la seconda opzione non è corretta e in effetti significa "posizione di aggiornamento" e non "aggiorna la posizione". Ma è fin troppo facile fare questo errore, specialmente in casi di parole ambigue come "aggiornamento". Giocare in sicurezza. Non confondere qualcuno di nuovo solo per aver risparmiato qualche secondo del tuo tempo.

/// <summary> blocchi sono utilizzati per generare documentazione per IntelliSense e documentazione API .

Quindi, se questa è un'API pubblica, dovresti sempre includere almeno un commento di <summary> , anche se lo scopo della funzione dovrebbe essere auto -evidente ai lettori.

Tuttavia, questa è l'eccezione alla regola; in generale, ricorda di ASCIUGARE (Non ripeterti) .

Inserisci commenti del tipo solo se sai come trarrai vantaggio da cose del genere; altrimenti basta cancellarli.

_{Per me, il caso di clear benefit era quando c'era un controllo automatico per i commenti mancanti e stavo usando quel controllo per rilevare il codice in cui erano necessarie informazioni importanti Essere riempito; per questo stavo davvero riempiendo alcuni segnaposti - giusto per assicurarmi che il rapporto dello strumento non contenga "falsi allarmi".}

Penso che ci sia sempre un modo per evitare la duplicazione evidente . Nel corso degli anni ho iniziato a utilizzare "template filler" di coppia per casi come i tuoi - per lo più come nome auto-descrittivo e vedi sopra .

Per questo particolare esempio, userei qualcosa di "tipo auto-descrittivo" (supponendo che non sia il caso in cui spazzare via farebbe il lavoro), in quel modo:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Esempio quando potrei usare vedere sopra riempitivi di tipo sarebbe Javadoc commenti che richiedono campi dedicati per il valore di ritorno, i parametri e le eccezioni. Abbastanza spesso, trovo che sia più sensato descrivere la maggior parte o anche tutte queste in una frase di riepilogo singola, il metodo che restituisce < descrive cosa viene restituito > per i parametri forniti < descrive parametri > . In casi come questo, riempio i campi richiesti formalmente con vedi sopra , indirizzando il lettore alla descrizione di riepilogo.}

Ecco una domanda che mi piace chiedermi quando devo aggiungere un commento in una sezione di codice: cosa posso trasmettere per aiutare la prossima persona a comprendere meglio l'intento del codice in modo migliore , in modo che possano aggiornarlo, correggerlo o estenderlo più velocemente e in modo più affidabile?

A volte la risposta corretta a questa domanda è che non c'è nulla che tu possa aggiungere a quel punto nel codice, perché hai già selezionato nomi e convenzioni che rendono l'intento più ovvio che possa essere. Ciò significa che hai scritto un solido codice di auto-documentazione e che l'inserimento di un commento avrebbe probabilmente penalizzato più di quanto sarebbe stato utile. (Si noti che i commenti ridondanti possono effettivamente danneggiare l'affidabilità del codice nel tempo rallentando la sincronizzazione con il codice reale nel tempo e rendendo così più difficile decifrare il vero intento.

Tuttavia, in quasi tutti i programmi e in tutti i linguaggi di programmazione, incontrerai dei punti in cui determinati concetti e decisioni critici fatti dal programmatore originale - da te - non saranno più evidenti nel codice. Questo è praticamente inevitabile perché un buon programmatore sempre programmi per il futuro - cioè, non solo per far funzionare il programma una volta, ma per fare tutte le sue numerose correzioni e versioni future ed estensioni e modifiche e porte e chissà che anche funzionano correttamente. Quest'ultima serie di obiettivi è molto più difficile e richiede molto più pensiero per fare bene. È anche molto difficile esprimersi bene nella maggior parte dei linguaggi informatici, che sono più focalizzati sulla funzionalità - cioè, per dire cosa deve fare la questa versione del programma, in questo momento, al fine di renderlo soddisfacente.

Ecco un semplice esempio di ciò che intendo. Nella maggior parte delle lingue, una rapida ricerca in linea di una piccola struttura di dati avrà una complessità tale che chi la guarda per la prima volta probabilmente non riconoscerà immediatamente di cosa si tratta. Questa è un'opportunità per un buon commento, perché puoi aggiungere qualcosa sull'intento del tuo codice che un lettore successivo probabilmente apprezzerà immediatamente come utile per decifrare i dettagli.

Viceversa, in linguaggi come il linguaggio basato sulla logica Prolog, esprimere la ricerca di una piccola lista può essere così incredibilmente banale e succinta che qualsiasi commento che potresti aggiungere sarebbe solo rumore. Quindi, un buon commento è necessariamente dipendente dal contesto. Ciò include fattori come i punti di forza della lingua che stai utilizzando e il contesto generale del programma.

La linea di fondo è questa: pensa al futuro. Chiediti cosa è importante e ovvio su come il programma dovrebbe essere compreso e modificato in futuro. [1]

Per quelle parti del tuo codice che sono veramente auto-documentanti, i commenti aggiungono solo rumore e aumentano il problema di coerenza per le versioni future. Quindi non aggiungerli lì.

Ma per quelle parti del tuo codice in cui hai preso una decisione critica da diverse opzioni, o in cui il codice stesso è abbastanza complesso da rendere il suo scopo oscuro, aggiungi le tue conoscenze speciali sotto forma di un commento. Un buon commento in questo caso è quello che consente a qualche futuro programmatore di sapere che cosa deve essere mantenuto lo stesso - questo è il concetto di un'asserzione invariante, incidentalmente - e cosa è OK da cambiare.

[1] Questo va al di là del problema dei commenti, ma vale la pena di tirarlo fuori: se trovi che hai un'idea molto chiara di come il tuo codice potrebbe cambiare in futuro, dovresti pensare oltre a fare solo un commento e incorporare tali parametri all'interno del codice stesso, poiché questo sarà quasi sempre un modo più affidabile per garantire l'affidabilità delle versioni future del codice rispetto al tentativo di utilizzare i commenti per indirizzare qualche persona futura sconosciuta nella giusta direzione. Allo stesso tempo, si vuole anche evitare la generalizzazione eccessiva, dal momento che gli umani sono notoriamente cattivi nel predire il futuro, e questo include il futuro dei cambiamenti del programma. Quindi, cerca di definire e catturare dimensioni ragionevoli e comprovate del futuro a tutti i livelli di progettazione del programma, ma non lasciarti distrarre da un esercizio di eccessiva generalizzazione che è improbabile che paghi a lungo termine.

Nel mio codice, lascerò spesso le tautologie dei commenti sul posto, inclusi quelli particolarmente eclatanti come:

<?php
// return the result
return $result;
?>

... che ovviamente contribuisce poco a rendere il codice più comprensibile da una prospettiva esplicativa.

Nella mia mente, tuttavia, questi commenti hanno ancora un valore, se aiutano a mantenere la coerenza visiva dei pattern di colore nella evidenziatrice della sintassi .

Penso che il codice abbia una struttura molto simile alla lingua inglese, nel senso che ci sono "frasi" e "paragrafi" (anche se un "paragrafo" può consistere interamente di una singola "frase"). Di solito includo un riepilogo di riga e un riepilogo di una riga sopra ogni "paragrafo". Ad esempio:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE 'id' = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ignora il codice incompleto, le iniezioni SQL, ecc. Hai un'idea.)

Per me, il commento finale aggiunge genuinamente valore al codice, semplicemente perché aiuta a delineare visivamente un "paragrafo" da un altro mantenendo uno schema di colorazione coerente.

I commenti dovrebbero essere usati per fare una delle seguenti azioni.

1. Informazioni per i generatori di documenti da afferrare. Questo non può essere sottovalutato, questo è estremamente importante.
2. Avvisi sul perché un pezzo di codice è così com'è e su quali altre considerazioni. Mi sono occupato del codice scritto in 2 linguaggi di programmazione. Una parte fondamentale di questo era avere una struttura comune tra le due lingue. Un commento in entrambe le sedi che informa l'utente che se cambiano questo numero, devono anche cambiarne un altro è estremamente utile.
3. Scrivi le note per spiegare perché una parte di codice particolarmente strana è così com'è. Se dovessi pensare a come far funzionare un pezzo di codice in un modo particolare, e la soluzione non è evidente fin dall'inizio, probabilmente merita una spiegazione su cosa stavi tentando di fare.
4. Etichettatura degli input / output, se non sono chiari. È sempre utile sapere quali sono gli input che ci si aspetta che siano e in che formato si trovano.

I commenti non dovrebbero essere usati per fare quanto segue:

1. Spiega cose che sono estremamente ovvie. Una volta ho visto un codice legacy come questo: page=0; // Sets the page to 0 . Penso che ogni individuo competente possa capirlo.

Vorrei rimuovere la tautologia ma mantenere il commento, vorrei commentare le proprietà e i nomi delle variabili dando un valore di esempio, in modo che l'utilizzo sia chiaramente compreso:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Ora so esattamente cosa va lì, e dal commento ho un'idea chiara su come usarlo.

Direi che dipende dallo scopo dei commenti.

Se devono essere usati per generare documentazione da usare dal team che lo costruisce (o se sono solo commenti in linea per spiegare le cose), allora penso che sia accettabile lasciarlo fuori. Si può tranquillamente presumere che sia auto-esplicativo; e quando non lo è, ci sono altri membri del team nelle vicinanze che possono spiegarlo. Certo, se risulta che non è evidente per molte persone, dovresti aggiungerlo.

Se i commenti genereranno la documentazione per un gruppo geograficamente distante, inserirò ogni frammento di documentazione.

Penso che questo argomento sia stato ampiamente discusso sotto nomi come "commenti: anti-schemi", o "sono commenti un odore di codice?" ( un esempio ).

Tendo ad essere d'accordo con l'idea generale che i commenti dovrebbero aggiungere nuove informazioni, non duplicare. Aggiungendo commenti banali come questo, si sta violando DRY e diminuendo il rapporto segnale / rumore del codice. Tendo a trovare commenti di alto livello che spieghino le responsabilità, le motivazioni alla base e l'utilizzo di esempio della classe molto più utile dei commenti per proprietà (in particolare quelli superflui).

Personalmente, nel tuo esempio, vorrei lasciare commenti (se non c'è davvero nulla di utile da aggiungere sulla proprietà).

Se riesci a scrivere codice che non richiede commenti, hai raggiunto la programmazione del nirvana!.

Meno commenti il tuo codice richiede migliore è il codice!

A comment like that is useless; what am I doing wrong?

Sembra inutile solo se sai già cosa fa UpdateLocation . "Aggiorna" qui un verbo o un nome aggiunto? Cioè, è qualcosa che aggiorna la posizione, o è la posizione dell'aggiornamento? Uno potrebbe dedurre quest'ultimo dal fatto che UpdateLocation è apparentemente una proprietà, ma il punto più grande è che a volte non fa male a dichiarare esplicitamente qualcosa che sembra ovvio.

A parte la documentazione compilata automaticamente, il codice dovrebbe documentarsi da solo, in modo che i commenti possano solo documentare dove il codice non è sufficiente per documentarsi.

"Location" è ovvio, ma "Update" potrebbe essere un po 'vago. Se non riesci a scrivere un nome migliore, puoi offrire maggiori dettagli nel commento? Aggiornamento di cosa? perché ne abbiamo bisogno? Quali sono alcune ipotesi (è nullo ammissibile)?