Stili di documentazione per commenti / in-code

Questa potrebbe essere una domanda stupida, ma è stata nella mia testa per un po 'e non riesco a trovare una risposta decente da nessun'altra parte.

Ho un insegnante che dice che dovremmo elencare esplicitamente ogni parametro con una descrizione, anche se ce n'è solo uno. Questo porta a molte ripetizioni:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Quando scrivi la documentazione nel codice, quanto sei dettagliato?

Per cominciare, sono d'accordo che la riga "Funzione:" nel tuo esempio è completamente ridondante. È stata anche la mia esperienza che le persone hanno insegnato a scuola per aggiungere quel tipo di commento continuando ad aggiungere quel tipo di commento nel loro codice di produzione.

I buoni commenti non ripetono cosa c'è nel codice. Rispondono alla domanda "Perché?" invece di "Cosa?" o come?" Coprono le aspettative in merito agli input e al comportamento del codice in determinate condizioni. Essi coprono il motivo per cui l'algoritmo X è stato scelto al posto di algoritmo di Y. In breve, esattamente le cose che non sarebbe ovvio per qualcun altro ¹ dalla lettura del codice.

^{1: Qualcun altro che abbia familiarità con la lingua in cui è scritto il codice. Non scrivere commenti per insegnare, commentare per integrare informazioni.}

Diverse lingue hanno funzionalità di generazione di documenti API come Ruby, Java, C # e C ++ (tramite uno strumento da riga di comando). Se ci pensi in questo modo, rende la scrittura dei documenti API molto più importante. Dopotutto, risponde alla domanda "come faccio ...?" Quindi non farò nulla di ripetitivo comeFunction: MyFunction quando il nome della funzione è evidente a tutti. Gli strumenti di generazione di documenti API sono abbastanza intelligenti da farlo per me. Tuttavia, sono utili i seguenti dettagli, in particolare sui metodi / funzioni pubblici:

• Riepilogo (cosa fa e, se pertinente, un riassunto di come usarlo)
• Elenco di parametri e cosa è previsto
• Quale sarà il valore di ritorno (output)
• Eventuali eccezioni che possono essere generate esplicitamente e perché

Questi possono diventare utili strumenti di riferimento quando si tenta di eseguire il debug del codice. Molti IDE useranno anche i documenti API nelle loro descrizioni degli strumenti mentre passi con il mouse sul nome della funzione.

Se è una lingua senza quelle funzionalità, i commenti aiutano, ma non altrettanto.

Se si tratta di un metodo API pubblico, sì, è necessario fornire una documentazione dettagliata, in particolare su parametri e comportamento previsto. Molte persone pensano che questo possa essere rilassato per metodi / funzioni private, YMMV.

Nel complesso preferisco scrivere codice pulito (piccoli metodi / funzioni che fanno una cosa e una cosa bene) con nomi di variabili sensibili. Ciò rende gran parte del codice auto-documentante. Tuttavia, certamente documento sempre eventuali casi limite, usi della concorrenza e algoritmi complessi.

In breve, pensa a te stesso come un po 'peggio da indossare alle 3 del mattino tra 3 mesi da oggi. Ti ringrazierai per i tuoi fantastici documenti pubblici invece di capire quale parametro (bandiera booleana) significa ...

È simile a come la maggior parte dei framework -Doc analizza la documentazione in-code (JavaDoc, PHPDoc, ecc.).

Da Java, generato automaticamente da IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Questo è lo stesso formato utilizzato per generare la documentazione per le funzionalità del linguaggio integrato - Esempio: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Questo formato è abbastanza utile perché mostra chiaramente a qualsiasi utente di terze parti come interfacciarsi con il tuo codice. Se le tue funzioni sono metodi privati ​​che vengono utilizzati solo internamente, allora può essere un po 'inutile, ma immagino che il tuo insegnante stia cercando di metterti in una buona pratica fino a quando non avrai esperienza con questa distinzione.

L'unico bit che trovo spesso in qualche modo ridondante è la descrizione di ritorno - Di solito è quasi identica alla mia descrizione del metodo.

Esistono due scopi per i commenti:

1. Servono a ricordarti rapidamente cosa fa il tuo codice quando torni ad esso mesi / anni dopo. In questo modo non è necessario rileggere e analizzare il codice per aggiornare la memoria.
2. Inoltrano ad altre persone che potrebbero leggere o lavorare con il tuo codice su cosa sta facendo il tuo codice.

Ovviamente ci sono MOLTI modi diversi di affrontarlo, ma più sei accurato e coerente, meglio è. Un commento efficace richiede tempo per apprendere esattamente come una programmazione efficace. Tieni presente che è difficile vedere il punto dei commenti a scuola poiché nulla a cui stai lavorando è mai abbastanza grande da giustificarlo davvero, ma stanno solo cercando di presentartelo. E di solito il modo in cui ti insegnano a farlo è lo stile del tuo professore, non alcun tipo di standard. Sviluppa ciò che funziona per te. E ricorda ... c'è una cosa come un commento stupido! :) Esempio:

a += 1; //adds 1 to the value in a

Veramente? Grazie! LOL

Mi piace la documentazione dal sito Web di PHP, quindi uso qualcosa di simile per i miei commenti incorporati e l'utilizzo della sintassi di PHPDoc. Vedi l'esempio sotto.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

E come ha detto @Larry Coleman, i commenti in linea dovrebbero dire perché hai fatto un pezzo di codice.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Se è al servizio della generazione di Doc, allora i commenti dettagliati (anche se irritanti) sono probabilmente una buona cosa. Anche se devi renderlo un obiettivo del team rimanere aggiornato sui commenti e tenerli aggiornati.

Se fosse solo lo stile dei commenti, avrei problemi con esso. Commenti eccessivi possono danneggiare il codice tanto quanto l'aiuto. Non riesco a contare il numero di volte in cui ho trovato commenti nel codice non aggiornati e, di conseguenza, fuorvianti. Di solito ora ignoro i commenti e mi concentro sulla lettura del codice e sui test del codice per capire cosa fa e qual è l'intento.

Preferirei avere un codice chiaro non commentato conciso . Dammi alcuni test con affermazioni o metodi descrittivi e sono felice e informato.