Come affrontare la tautologia nei commenti? [chiuso]

A volte mi trovo in situazioni in cui la parte di codice che sto scrivendo è (o sembra essere ) così evidente che il suo nome sarebbe sostanzialmente ripetuto come un commento:

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

(Esempio C #, ma fai riferimento alla domanda come lingua-agnostica).

Un commento del genere è inutile; Che cosa sto facendo di sbagliato? È la scelta del nome che è sbagliata? Come potrei commentare meglio parti come questa? Dovrei semplicemente saltare il commento per cose come questa?

Nella maggior parte dei progetti a cui lavoro, non c'è molto tempo per scrivere commenti dettagliati su ogni singolo membro della classe.

Ciò non significa che non c'è tempo per i commenti; al contrario, c'è un sacco di tempo per i commenti tautologici che riportano indietro una versione riformulata di tutto ciò che viene commentato. Funzionano alla grande come punto di partenza .

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

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

E poi mentre continui a scrivere codice, quando non ricordi se si UpdateLocationè verificata la posizione in cui è stato eseguito l'aggiornamento o la posizione a cui è stato inviato l'aggiornamento, dovrai rivisitare il codice. È a questo punto che è necessario aggiungere ulteriori informazioni:

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

Se mai un altro programmatore ti chiede dei dettagli su un campo, aggiorna i commenti con quelle informazioni:

Che tipo di aggiornamento dovrebbe Example.UpdateLocationessere usato per archiviare?

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 dei bug che devono essere elaborati iterativamente. Lo scopo dei commenti è di aiutare a comprendere il codice quando lo rivisiti sei mesi dopo e non ricordi nulla sul funzionamento del programma.

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

I commenti non devono mai duplicare il tuo codice. I commenti non devono 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 di tipi, i contratti e simili), qual è la ragione per fare questa cosa, ecc.

Consiglierei di dare un'occhiata alla pratica di Programmazione letterata per una fonte d'ispirazione.

I commenti dovrebbero descrivere il codice, non duplicarlo. Questo commento dell'intestazione è solo duplicato. Lascialo fuori.

Lasciali fuori!

Normalmente, è buona norma rimuovere i commenti in cui le informazioni espresse in essi sono già presenti altrove. Se riesci a esprimere lo scopo di un metodo in modo chiaro e inequivocabile dandogli un buon nome, non è necessario un commento .

Mettili dentro!

Il tuo esempio illustra due eccezioni a questa regola:

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

In secondo luogo, "///" in C # indica un commento che deve essere utilizzato per generare automaticamente la documentazione. L'IDE utilizza questi commenti per i suggerimenti e ci sono strumenti (Sandcastle) che possono generare file di aiuto e così via da questi commenti. Pertanto, ci sono argomenti per inserire questi commenti anche se i metodi che documentano hanno già nomi descrittivi. Anche allora, tuttavia, molti sviluppatori esperti non vedono l'ora di duplicare le informazioni. Il fattore decisivo dovrebbe essere le esigenze di coloro ai quali è destinata la documentazione.

Sono fortemente in disaccordo con le risposte "non scrivere commenti". Perché? Vorrei sottolineare modificando un po 'il tuo esempio.

public Uri UpdateLocation ();

Quindi cosa fa questa funzione:

• Restituisce la "posizione di 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 "get / set" rivelano che la seconda opzione è errata e in effetti significa "aggiorna posizione" e non "aggiorna la posizione". Ma è troppo facile commettere questo errore, specialmente in casi di parole ambigue come "aggiornamento". Giocare in sicurezza. Non confondere qualcuno di nuovo con questo solo per risparmiare qualche secondo del tuo tempo.

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

Pertanto, se si tratta di un'API rivolta al pubblico, è necessario includere sempre almeno un <summary>commento, anche se lo scopo della funzione dovrebbe essere evidente per i lettori.

Tuttavia, questa è l'eccezione alla regola; in generale, ricordati solo di ASCIUGARE (non ripetere te stesso) .

Compila commenti del genere solo se sai come trarrai vantaggio da cose del genere; altrimenti semplicemente cancellali.

_{Per me, il caso di chiaro vantaggio è stato quando c'era un controllo automatico per i commenti mancanti e stavo usando quel controllo per rilevare il codice in cui era necessario compilare informazioni importanti; per questo stavo davvero riempiendo alcuni segnaposto - solo per assicurarmi che il rapporto degli strumenti non contenga "falsi allarmi".}

Penso che ci sia sempre un modo per evitare la palese duplicazione . Nel corso degli anni ho imparato a utilizzare un paio di "riempitori di modelli" per casi come il tuo - principalmente come il nome auto-descrittivo e vedi sopra .

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

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

_{Esempio in cui potrei usare vedere i riempitori tipo sopra sarebbero i commenti Javadoc che richiedono campi dedicati per valore di ritorno, parametri ed eccezioni. Abbastanza frequentemente, trovo che abbia più senso descrivere la maggior parte o anche tutte queste in una singola frase di riepilogo, metodo che restituisce <descrivi ciò che viene restituito> per i parametri forniti <descrivi i parametri> . In casi del genere, compilo i campi richiesti formalmente con la semplice vedi sopra , indicando il lettore alla descrizione sommaria.}

Ecco una domanda che mi chiedo quando penso se aggiungere un commento in una sezione di codice: cosa posso comunicare per aiutare la persona successiva a comprendere meglio l' intento generale del codice, in modo che possano aggiornare, correggere o estenderlo più velocemente e in modo più affidabile?

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

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

Ecco un semplice esempio di cosa intendo. Nella maggior parte delle lingue, una rapida ricerca in linea di una piccola struttura di dati avrà una complessità sufficiente che qualcuno che la guarderà per la prima volta probabilmente non riconoscerà immediatamente di cosa si tratta. Questa è l'occasione per un buon commento, perché è possibile aggiungere qualcosa circa la volontà del codice che un lettore in seguito probabilmente apprezzeranno immediatamente come utile per decifrare i dettagli.

Al contrario, in lingue come il linguaggio basato sulla logica Prolog, esprimere la ricerca di un piccolo elenco può essere così incredibilmente banale e succinto che qualsiasi commento che potresti aggiungere sarebbe solo rumore. Quindi, un buon commento dipende necessariamente 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 per te su come il programma dovrebbe essere compreso e modificato in futuro. [1]

Per quelle parti del codice che sono veramente auto-documentate, 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 oscuro il suo scopo, ti preghiamo di aggiungere le tue conoscenze speciali sotto forma di un commento. Un buon commento in questo caso è quello che fa sapere ad un futuro programmatore cosa deve essere mantenuto lo stesso - questo è il concetto di un'affermazione invariante, per inciso - e cosa può cambiare.

[1] Questo va oltre il problema dei commenti, ma vale la pena sollevare: se scopri di avere un'idea molto chiara di come il tuo codice potrebbe cambiare in futuro, dovresti probabilmente pensare oltre a fare un commento e incorporare quei parametri all'interno del codice stesso, poiché sarà quasi sempre un modo più affidabile per garantire l'affidabilità delle versioni future del codice rispetto al tentativo di utilizzare i commenti per guidare una persona futura sconosciuta nella giusta direzione. Allo stesso tempo, vuoi anche evitare un'eccessiva generalizzazione, dal momento che gli umani sono notoriamente cattivi nel predire il futuro, e questo include il futuro dei cambi di programma. Quindi, prova a definire e catturare dimensioni ragionevoli e comprovate del futuro a tutti i livelli di progettazione del programma, ma non

Nel mio codice, lascerò spesso in atto le tautologie dei commenti, comprese quelle particolarmente eclatanti come:

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

... che ovviamente contribuiscono poco in termini di rendere il codice più comprensibile da una prospettiva esplicativa.

Nella mia mente, tuttavia, questi commenti hanno ancora valore, se aiutano a mantenere la coerenza visiva dei motivi di colore nell'evidenziatore della sintassi .

Penso che il codice abbia una struttura molto simile alla lingua inglese, in quanto vi sono "frasi" e "paragrafi" (anche se un "paragrafo" può consistere interamente in una singola "frase"). Di solito includo un'interruzione di riga e un riepilogo di una riga sopra ogni "paragrafo". Per 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 di SQL, ecc. L'idea è stata presa.)

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

I commenti devono essere utilizzati per effettuare una delle seguenti operazioni.

1. Informazioni da raccogliere per i generatori di documenti. Questo non può essere minimizzato, questo è estremamente importante.
2. Avvertimenti sul perché un pezzo di codice è come è e quali altre considerazioni. Mi sono occupato del codice scritto in 2 linguaggi di programmazione. Una parte fondamentale di questo era di avere una struttura comune tra le due lingue. Un commento in entrambe le posizioni informa l'utente che se cambiano questo numero, devono anche cambiare un altro è estremamente utile.
3. Scrivi note per spiegare perché un pezzo di codice dall'aspetto particolarmente strano è così com'è. Se hai dovuto pensare a come far funzionare un pezzo di codice in un modo particolare, e la soluzione non è evidente fin dall'inizio, probabilmente vale la pena di spiegarti cosa stavi cercando di fare.
4. Etichettatura di ingressi / uscite, se non sono chiari. È sempre bene sapere quali saranno i tuoi input e in quale formato sono.

I commenti non devono essere usati per fare quanto segue:

1. Spiega cose estremamente ovvie. Una volta ho il codice legacy sega in questo modo: page=0; // Sets the page to 0. Penso che qualsiasi persona competente potrebbe capirlo.

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

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

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

Direi che dipende dallo scopo dei commenti.

Se devono essere utilizzati per generare documentazione per l'utilizzo da parte del team che lo costruisce (o se sono solo commenti incorporati per spiegare le cose), penso che sia accettabile lasciarlo fuori. Si può presumere che sia autoesplicativo; e quando non lo è, ci sono altri membri del team nelle vicinanze che possono spiegarlo. Naturalmente, se si scopre che non è evidente per molte persone, dovresti aggiungerlo.

Se i commenti genereranno documentazione per un team geograficamente distante, metterei tutta la documentazione lì dentro.

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

Tendo a concordare con l'idea generale che i commenti dovrebbero aggiungere nuove informazioni, non duplicati. Aggiungendo commenti così banali, stai 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'uso esemplificativo della classe molto più utile dei commenti per proprietà (specialmente quelli superflui).

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

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

Meno commenti richiede il codice, migliore è il codice!

Un commento del genere è inutile; Che cosa sto facendo di sbagliato?

Sembra inutile solo se sai già cosa UpdateLocationfa. "Aggiornamento" qui è un verbo o un sostantivo aggiunto? Cioè, si tratta di qualcosa che aggiorna la posizione o è la posizione dell'aggiornamento? Si potrebbe dedurre quest'ultimo dal fatto che UpdateLocationapparentemente è una proprietà, ma il punto più grande è che a volte non fa male affermare esplicitamente qualcosa che sembra ovvio.

A parte la documentazione compilata automaticamente, il codice dovrebbe documentare se stesso, quindi i commenti dovrebbero documentare solo dove il codice non è sufficiente per documentare se stesso.

"Posizione" è abbastanza ovvio, ma "Aggiornamento" 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 alcuni presupposti (è nullo ammissibile)?