Buone pratiche nella scrittura di commenti e documentazione

20

Commentare al giorno d'oggi è più facile che mai. In Java, ci sono alcune belle tecniche per collegare i commenti alle classi e gli IDE Java sono bravi a creare shell di commenti per te. Lingue come Clojure consentono persino di aggiungere una descrizione di una funzione nel codice della funzione stessa come argomento.

Tuttavia viviamo ancora in un'epoca in cui ci sono spesso commenti obsoleti o scadenti scritti da bravi sviluppatori - sono interessato a migliorare la solidità e l'utilità dei miei commenti.

In particolare, sono interessato a Java / Clojure / Python qui, ma le risposte non devono essere specifiche della lingua.

Esistono tecniche emergenti che convalidano i commenti e rilevano automaticamente commenti "deboli" (ad esempio commenti con numeri magici, frasi incomplete, ecc.) O commenti errati (ad esempio, il rilevamento di variabili errate o simili).

E ancora più importante: ci sono "politiche di commento" o strategie accettate? Ci sono molti consigli là fuori su come programmare - ma che dire di "come commentare?"

— jayunit100
fonte

40

I nomi / la documentazione dovrebbero dirti cosa stai facendo.
L'implementazione dovrebbe dirti come lo stai facendo.
I commenti dovrebbero dirti perché lo fai nel modo in cui lo fai.

— maniaco del cricchetto
fonte

6

commenti dovrebbero anche dirvi perché si sta non facendo altro modo - cioè importanti scelte progettuali - perché manutentori future non avranno queste informazioni in altro modo.

2

Credo che molte volte un commento dovrebbe dire COSA stai facendo anche tu. Questa idea del solo "perché" commenti è un anti-modello secondo me. È un mito che tu possa scrivere tutto il codice in modo abbastanza chiaro che qualsiasi programmatore può capirlo a colpo d'occhio, e la mia esperienza è che la maggior parte dei programmatori pensa di scrivere codice pulito no. È come dire: "Non devo nominare questa funzione in modo descrittivo perché chiunque può semplicemente leggere il codice nella funzione per vedere cosa fa". - non ha nemmeno senso, vero?

— dallin

2

@dallin se il tuo codice non è chiaro su cosa sta facendo; considerare di refactoring. altrimenti aggiungi un commento che spiega perché è implementato in quel modo (che spiega anche come meglio). Il tuo confronto con nomi descrittivi è mele / arance, un nome descrittivo chiarisce dove viene utilizzata la funzione e potresti non avere accesso al codice sorgente della funzione.

— maniaco del cricchetto,

@dallin: "È un mito che tu possa scrivere tutto il codice in modo abbastanza chiaro che qualsiasi programmatore possa capirlo a colpo d'occhio", zio Bob vorrebbe avere una parola con te. - "Non devo nominare questa funzione in modo descrittivo perché chiunque può semplicemente leggere il codice nella funzione per vedere cosa fa.", Dare nomi chiari e chiari a variabili e metodi è esattamente come i programmatori dovrebbero chiarire quale sia il loro codice sta facendo!

— klaar,

14

Questo potrebbe essere controverso, ma il mio consiglio sarebbe di scrivere il più possibile commenti. Utilizzare invece nomi di classi chiari e chiari, nomi di variabili e nomi di metodi. Scrivi il tuo codice nel modo più chiaro possibile; e considera questo come l'attributo più importante del tuo codice (oltre a quello che soddisfa i suoi requisiti). Scrivi un commento solo se hai reso un metodo il più chiaro possibile e pensi ancora che richieda ulteriori spiegazioni.

E avere una pratica organizzativa, che ogni volta che qualcuno cambia una classe in qualsiasi modo, deve assicurarsi che i commenti siano ancora tutti corretti.

— Dawood dice di ripristinare Monica
fonte

1

Questo è un buon inizio, ma penso che per soddisfare la domanda del PO dovrai scrivere qualcosa che affronti le sue attuali preoccupazioni riguardo alla validazione automatica.

— Robert Harvey,

2

+1 - Penso anche che i commenti dovrebbero essere usati solo per spiegare perché il codice è stato scritto. So cosa if (a == b) then c();fa, ma se non so perché lo fa - è allora che dovrebbe essere usato un commento :)

— Deco

Deco - Sono completamente d'accordo. I commenti sono positivi quando voglio capire come un particolare metodo si adatta al processo nel suo insieme. In altre parole, PERCHÉ chiameresti questo metodo o PERCHÉ fa quello che fa.

— Dawood dice di ripristinare Monica il

Oltre a chiarire il codice scritto, dovremmo anche assicurarci di conservare idee, pensieri, ecc. A livello di codice usando i commenti TODO. Ad esempio, se vedi una funzione / classe in grado di gestire correttamente le dimensioni dei dati attuali, ma potenzialmente non riuscirà a gestire il carico dopo 2 anni, quindi assicurati di scrivere la tua osservazione lì usando il commento TODO. I futuri sviluppatori apprezzeranno davvero i tuoi sforzi. Non tentare mai di annotare queste cose in un documento txt / word separato, mentre si scrive codice, nessuno fa realmente riferimento a tali documenti.

— TechCoze,

vedi anche: "I commenti sono un odore di codice"

— moscerino

5

Non sono sicuro di altre lingue, ma python ti consente di scrivere test di testo che sono una forma di commenti auto- validanti . Ovviamente, non dovrebbero essere usati al posto di test di unità reali, ma sono un metodo rapido e semplice per documentare funzioni specifiche che potrebbero non essere così ovvie come dovrebbero essere. Hanno il vantaggio aggiuntivo di poter eseguire i test dei commenti per verificare che i commenti siano ancora corretti (almeno la parte di essi che contiene i test).

— Josh Smeaton
fonte

1

E Sphinx confronta il codice con la documentazione per fornire metriche di copertura.

— S. Lott

3

Una delle posizioni più autorevoli per trovare come utilizzare i commenti di codice per generare automaticamente la documentazione è sicuramente doxygen . Sebbene ci possano essere più di tali strumenti.

Questo definisce lo standard di scrittura dei commenti che dovrebbe essere seguito per generare automaticamente la documentazione. Tuttavia, questo dà più di una struttura ma non convalida semanticamente; per esempio non può verificare se hai usato un inglese fuorviante per descrivere lo scopo di una funzione!

Mentre, questa è la cosa migliore che rende strutturati i commenti, personalmente ritengo che ci sia più documentazione necessaria per rendere il codice più gestibile in quanto tale. Qualche tempo fa c'era una domanda in P.SE Il codice può essere la documentazione negli strumenti di sviluppo open source? Quanto è frequente? Naturalmente, questo vale anche per i progetti non open-source.

Per rendere il codice più gestibile, è praticamente più importante che esista una documentazione esterna che aiuti a creare una struttura su come trattare il codice, quindi i commenti all'interno del codice dovrebbero essere limitati per vedere

Penso che, se si desidera definire le politiche per la scrittura di commenti, è necessario includere un approccio olistico incluso nello standard di codifica. Vedi questo: quali potrebbero essere alcune insidie nell'introduzione di una guida di stile e documentazione che genera software in un team di sviluppo?

Di solito un commento costituisce meno del 5% del codice. E in pratica mentre le stesse revisioni del codice attirano molte meno attenzioni (rispetto ad altri aspetti dello sviluppo) è praticamente difficile che anche i commenti vengano rivisti.

— Dipan Mehta
fonte

1

Non sono d'accordo con l'ultima frase qui. Ho appena concluso un contratto, lavorando con un team leader che ha fornito recensioni molto dettagliate. Le sue recensioni includevano sempre i commenti: come erano formulati, se i nomi delle variabili erano corretti, se contenevano tutte le informazioni che un futuro sviluppatore avrebbe potuto voler sapere. In poco tempo, sapevo cosa si aspettava di vedere in ogni commento ed ero in grado di produrre commenti secondo il suo standard. Quindi, a condizione che la politica organizzativa abbia revisioni del codice e includa commenti nella revisione del codice, allora accadrà.

— Dawood dice di ripristinare Monica il

Questo di solito è l'unico tipo di commento che scrivo, specialmente per i metodi per documentare cosa succede e cosa ne esce (lavoro con linguaggi tipicamente vaghi).

— DanMan,

2

Esistono tecniche emergenti che convalidano i commenti e rilevano automaticamente commenti "deboli" (ad esempio commenti con numeri magici, frasi incomplete, ecc.) O commenti errati (ad esempio, il rilevamento di variabili errate o simili).

Esiste una tecnica ben nota - si chiama "revisione del codice" e ha una sorella chiamata "programmazione coppia". Non aspettarti nulla di "automagicamente" qui.

E ancora più importante: ci sono "politiche di commento" o strategie accettate? Ci sono molti consigli là fuori su come codificare --- ma che dire di "come commentare?"

"Codice completo" contiene non solo tutto su come codificare, ma anche i capitoli su "come commentare", in particolare su come scrivere codice autocompattante.

— Doc Brown
fonte

+1 per il codice completo. Clean Code di Robert Martin ha anche un buon capitolo sulla scrittura di elogi utili. Non sono sicuro del mondo Java, ma nel mondo .NET abbiamo Resharper, che può validare 'automagicamente' i riferimenti agli elementi del codice nei commenti :)

— MattDavey,

0

Specifico per Java, una fonte che mi è piaciuta è Oracle How to Write Doc Comments for the Javadoc Tool :

Questo documento descrive la guida di stile, i tag e le convenzioni di immagine che utilizziamo nei commenti della documentazione per i programmi Java scritti in Java Software, Sun Microsystems.

E elemento 44: scrivere commenti doc per tutti gli elementi API esposti :

Se un'API deve essere utilizzabile, deve essere documentata. Tradizionalmente la documentazione API veniva generata manualmente e mantenerla sincronizzata con il codice era un lavoro ingrato. L'ambiente di programmazione Java semplifica questa attività con l'utilità Javadoc. Javadoc genera automaticamente la documentazione API dal codice sorgente con commenti di documentazione appositamente formattati, più comunemente noti come commenti doc.

da Effective Java 2nd Edition .

— EGHM
fonte