Le migliori pratiche nella scrittura e nella documentazione dei commenti

• Nomi / documentazione dovrebbero dirti cosa stai facendo.

• L'implementazione dovrebbe dirti come stai facendo.

• i commenti dovrebbero dirti perché lo fai nel modo in cui lo fai.

Questo potrebbe essere controverso, ma il mio consiglio sarebbe quello di scrivere il più possibile come commenti. Usa invece nomi di classi chiari, chiari, nomi di variabili e metodi. Scrivi il tuo codice nel modo più chiaro che puoi; e considera questo come l'attributo più importante del tuo codice (diverso da quello che soddisfa i suoi requisiti). Scrivi un commento solo se hai reso il metodo il più chiaro possibile e ritieni 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.

Non sono sicuro di altre lingue, ma python ti permette di scrivere doct che sono una forma di commenti auto-validanti. Ovviamente, non dovrebbero essere usati al posto dei veri test unitari, ma sono un metodo rapido e semplice per documentare funzioni specifiche che potrebbero non essere così ovvie come dovrebbero essere. Vengono con l'ulteriore vantaggio di essere in grado di eseguire i test dei commenti per verificare che i commenti siano ancora corretti (almeno la parte di essi che contiene test).

Una delle posizioni più autorevoli per trovare come utilizzare il commento di codice per generare automaticamente la documentazione è sicuramente doxygen . Anche se potrei avere più di questi strumenti.

Questo definisce lo standard di scrittura di 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ò controllare se hai usato l'inglese ingannevole per descrivere lo scopo di una funzione!

Mentre questa è la cosa migliore che rende i commenti strutturati, personalmente ritengo che ci sia più documentazione necessaria per rendere il codice più manutenibile 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 spesso è? 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, e quindi i commenti all'interno del codice dovrebbero essere ristretti per vedere

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

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

Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).

Esiste una tecnica ben nota - si chiama "code-review" e ha una sorella chiamata "pair-programming". Non aspettarti nulla "automagicamente" qui.

And more importantly : Are there accepted "commenting-policies" or strategies out there ? There is plenty of advice out there on how to code --- but what about "how to comment?"

"Codice completo" contiene non solo tutto su come codificare, ma anche i capitoli su "come commentare ", in particolare su come scrivere il codice di auto-documentazione.

Specifico per Java, una fonte che ho apprezzato è Oracle Come scrivere commenti di un documento per lo strumento Javadoc :

This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Sun Microsystems.

E Item 44: Scrivi i commenti del doc per tutti gli elementi API esposti :

If an API is to be usable, it must be documented. Traditionally API documentation was generated manually, and keeping it in sync with code was a chore. The Java programming environment eases this task with the Javadoc utility. Javadoc generates API documentation automatically from source code with specially formatted documentation comments, more commonly known as doc comments.

da Seconda edizione Java efficace .