Stili di documentazione per commenti / codici

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 ad aggiungere quel tipo di commento che continua 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?" Riguardano le aspettative sugli input e il comportamento del codice in determinate condizioni. Coprono perché l'algoritmo X è stato scelto al posto dell'algoritmo Y. In breve, esattamente le cose che non sarebbero ovvie a 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). Quando ci pensi in questo modo, rende la scrittura dei documenti API molto più importante. Dopo tutto, risponde alla domanda "come faccio ...?" Quindi non farò nulla di ripetitivo come Function: MyFunction quando il nome della funzione è chiaro per tutti da vedere. Gli strumenti di generazione di documenti API sono abbastanza intelligenti da farlo per me. Tuttavia, i seguenti dettagli sono utili, in particolare sui metodi / funzioni pubblici:

• Riepilogo (che cosa fa e, se pertinente, un riassunto su come usarlo)
• Elenco dei parametri e cosa è previsto
• Quale sarà il valore restituito (output)
• Qualsiasi eccezione che può essere generata in modo esplicito e perché

Questi possono diventare utili strumenti di riferimento quando si tenta di eseguire il debug del codice. Molti IDE utilizzeranno anche i documenti API nei loro suggerimenti di strumenti quando passi il mouse sopra il nome della funzione.

Se è una lingua senza queste caratteristiche, i commenti aiutano, ma non così tanto.

Se si tratta di un metodo API pubblico, allora si dovrebbe fornire una documentazione dettagliata, in particolare sui parametri e il comportamento previsto. Molte persone ritengono che questo possa essere rilassato per metodi / funzioni privati, YMMV.

Nel complesso preferisco scrivere codice pulito (piccoli metodi / funzioni che fanno una cosa e una cosa bene) con nomi di variabili sensibili. Questo rende molto del tuo codice auto-documentante. Tuttavia, di sicuro documenterò sempre casi limite, usi della concorrenza e algoritmi complessi.

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

Questo è simile al modo in cui 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 incorporato - Esempio: link

Questo formato è molto 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 farti diventare una buona pratica finché non avrai tutti esperienza con questa distinzione.

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

Ci sono due scopi per i commenti:

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

Ovviamente ci sono molti MOLTI modi per avvicinarsi a questo, ma il più completo e coerente sei il migliore. Un commento efficace richiede tempo per imparare come fa la programmazione efficace. Tenete a mente che è difficile vedere il punto dei commenti a scuola, visto che nulla su cui state lavorando è mai abbastanza grande da giustificarlo veramente, ma stanno solo provando a presentarlo a voi. E di solito il modo in cui ti insegni a farlo è lo stile del tuo professore, che non ha 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

Davvero? Grazie! LOL

Mi piace la documentazione del sito Web PHP, quindi uso qualcosa di simile per i miei commenti in linea e usando la sintassi PHPDoc. Vedi l'esempio qui 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 spiegare 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, i commenti dettagliati (anche se irritanti) sono probabilmente una buona cosa. Anche se devi renderlo un obiettivo della squadra per rimanere in cima ai commenti e tenerli aggiornati.

Se è solo lo stile di commento, avrei problemi con esso. I 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 ignoro i commenti ora e mi concentro sulla lettura del codice e sui test del codice per capire cosa fa e qual è l'intento.

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