Qual è il rapporto codice / commento dorato? [chiuso]

https://stackoverflow.com/questions/111563

02-07-2019
|

Domanda

Esiste un rapporto codice / commento che consideri un segno di buona (cattiva) salute del codice?

Puoi fornire esempi di progetti open source che sono considerati ben codificati e il loro rispettivo rapporto di commenti?

(Mi rendo conto che nessun rapporto è "vero" per ogni progetto e potrebbero benissimo esserci progetti schifosi che mostrano questo rapporto aureo teorico. Ancora ...)

Soluzione

I commenti dovrebbero essere molto rari e preziosi, esprimendo quasi sempre il "perché" e mai il "come" (l'eccezione è quando il come è complesso e non facilmente distinguibile dal codice).

Ogni commento è un suggerimento che potrebbe essere necessario eseguire il refactoring per rendere più chiaro l'intento del codice. Ogni commento rischia di diventare obsoleto non appena viene scritto.

Non abbiamo quasi alcun commento oltre ai commenti XML nel nostro progetto xUnit.net , ma alcune persone sembrano trovare il codice chiaro e di facile lettura. :)

Altri suggerimenti

Chiunque debba correggere il codice di un altro programmatore dirà quanti più commenti possibili . Il grosso problema con il vecchio codice è: " Vedi cosa fa il codice. Vedi che questo è il problema. Ma non sai perché il programmatore lo abbia scritto in questo modo. & Quot;

Per capire un bug devi sapere:

cosa dovrebbe fare il codice (non cosa fa il codice) e perché.
Il contratto di ogni funzione. Ad esempio, se esiste una NullPointerException, dov'è il bug? Nella funzione o nella funzione chiamante?
Su ogni Hack viene descritto come riprodurre il problema (versione in lingua, sistema operativo, versione del sistema operativo). Ad esempio abbiamo molti hack per una vecchia VM Java che non è più supportata. Ma non siamo sicuri di poterlo rimuovere perché non sappiamo come riprodurli.

Abbiamo un rapporto del 2-3%, che è troppo pochi. Penso che il 10% sia positivo per progetti di grandi dimensioni o di lunga durata.

Siamo spiacenti, non esiste una regola empirica. Framework e librerie, ad esempio, richiedono molti più commenti perché i programmatori saranno clienti e non avranno il tempo di leggere il codice ogni volta che devono invocare un metodo.

I progetti in cui stai scrivendo / leggendo il codice richiedono meno commenti e dovrebbero cercare di migliorare la leggibilità del codice anziché il rapporto commento / codice.

Cordiali saluti

I commenti non spiegano semplicemente il codice, ma guidano anche il debugger che sta cercando il pezzo di codice che fa qualcosa.

Il recupero della cronologia degli ordini di un cliente o il calcolo della visibilità di un giocatore nemico possono richiedere dozzine di righe di codice e persino un programmatore esperto può impiegare diversi minuti per essere sicuro che sia quello che fa. Un commento che dice "recuperare la cronologia degli ordini del cliente" consente al debugger di non investigare affatto quel codice, se sa che la cronologia degli ordini non è il problema.

Commento tutto ciò che penso sia ambiguo o debba essere spiegato. Spesso, commento eccessivo. Perché? Perché non sai mai chi lavorerà sul tuo codice. Mi piace immaginare una situazione in cui sostituiscono metà della squadra con scimmie che capiscono che quando premono entrano su una linea, ottengono una banana. Quindi, se almeno imparano a leggere, non cambieranno la mia logica senza prima leggere i commenti.

Caso e punto:

// Delete the helloworld file
exec("rm -f helloworld.txt")

Non verrà modificato in:

exec("rm -rf /")

È improbabile, lo so, ma anche alcuni buoni sviluppatori sono noti per cambiare logica perché non sembra corretto e non perché si è verificato un errore o una modifica dei requisiti .

Penso che tutti possano concordare sul fatto che 0 commenti possono essere generalmente considerati codice sub-documentato. Ricorda che anche il codice più autocompattante può documentare solo ciò che è lì ; mai ciò che è stato intenzionalmente escluso, ottimizzato, provato e scartato, ecc. Avrai sempre bisogno dell'inglese, in sostanza, nei tuoi file sorgente, o sei tenuto a tralasciare importanti avvertenze e decisioni di progettazione.

Sono interessato a come questi solidi principi che voi ragazzi state sostenendo (con i quali sono pienamente d'accordo finora) traducono in statistiche di codice. In particolare, quali progetti open source sono considerati ben documentati (non eccessivamente) e qual è il rapporto commenti lì.

Ho una regola empirica molto semplice: se hai bisogno di fermarti e pensare più di ~ 15 secondi durante la codifica di un pezzo di codice (diciamo, una funzione o un ciclo complesso, ecc.), allora quel pezzo di codice ha bisogno di un commento.

Funziona davvero bene per me. La prossima volta che tu, o qualcuno al tuo livello di comprensione della base di codice generale, ti imbatti in quel pezzo di codice, vedrà immediatamente perché è stato fatto nel modo in cui è stato fatto.

LOC / LOcomment = yearsofexp / 5

La mia regola è questa: se c'è qualcosa che deve essere detto e il codice può non essere fatto per esprimerlo, allora puoi scrivere un commento. Altrimenti, se il codice può esprimere l'idea, allora devi esprimere l'idea nel codice o nei suoi test.

Se segui questa regola, allora il tuo codice dovrebbe avere bisogno di commenti solo quando ha a che fare con qualche problema evidente nell'hardware o nel sistema operativo, o quando l'algoritmo più ovvio non è la scelta migliore. Questi sono " questo è strano perché " commenti, e in realtà sono solo un meccanismo di coping. La maggior parte delle volte i commenti nel codice sono in realtà solo scuse per non averlo scritto in un modo più ovvio, e tali commenti dovrebbero essere annullati e quindi eliminati.

Anche i buoni commenti spesso diventano bugie nel tempo, quindi le informazioni in luoghi non eseguibili, non testabili come i commenti devono essere guardate con sospetto. Ancora una volta, la risposta è innanzitutto eliminare il commento, quindi eliminarlo.

Il mio rapporto ideale è zero. Tuttavia, il mondo è tutt'altro che ideale, quindi accetto i commenti quando non c'è altro modo per comunicare un'idea importante.

Dovrebbero esserci dei commenti dove li ritieni necessari. Non di più e non di meno.

Commenta le parti che ritieni di non capire dopo 6+ settimane di pausa quando guardi di nuovo il codice

Cerco di mantenere i commenti al minimo. Il codice dovrebbe essere autoesplicativo e mentre il codice sorgente tende a cambiare i commenti quasi sempre rimangono dietro come spiegazione errata.

Il rapporto codice / commento dorato è l'intersezione di

commenti necessari per ricordare a te stesso ciò che avevi in ??mente durante la codifica
commenti necessari per ricordare agli altri le cose che avevi in ??mente durante la codifica
commenti che il cliente è disposto a pagare (perché i buoni commenti costano tempo)
l'interesse dello sviluppatore a produrre codice offuscato a causa della sicurezza del lavoro (se lavora per un'azienda in cui uno sviluppatore può cavarsela)

Questo mostra anche perché quel rapporto è diverso per ogni progetto e ogni squadra.

Non esiste un rapporto aureo. Il numero di commenti dipende molto dalla complessità intrinseca del codice. Se stai solo scrivendo applicazioni CRUD, probabilmente non avrai bisogno di molti commenti. Se stai scrivendo un sistema operativo o un RDBMS, probabilmente dovrai commentare di più, in quanto eseguirai una codifica più complicata e dovrai rendere un po 'più esplicito il motivo per cui stai facendo le cose che stai facendo.

Se desideri alcuni dati del mondo reale sui rapporti di commento per diverse lingue, dai un'occhiata a Ohloh .

Ad esempio, puoi guardare le varie metriche per Fonte del kernel Linux.

Suppongo che nessuno possa darti cifre, ma dovrebbe essere molto più alto nei file di intestazione che nel sorgente.

Mi aspetto che il file header di una classe documenti tutte le classi / funzioni / etc accessibili pubblicamente includendo quel file header. Questo può essere un bel po 'di righe per documentare una funzione il cui prototipo è una singola riga (no, solo scegliere buoni nomi per le funzioni e i loro parametri non è abbastanza - può essere, ma spesso non lo è). Tre righe di commento per ogni riga di codice non sarebbero eccessive.

Per il codice effettivo, sarebbe molto più basso. Non sono d'accordo con gli estremisti che pensano che dovresti puntare a zero commenti, ma certamente se pensi di aver bisogno di commenti dovresti prima considerare se il codice potrebbe essere reso più chiaro.

Può variare abbastanza. Ad esempio, puoi avere un codice scritto così bene che i commenti sarebbero solo una perdita di tempo.

Hai bisogno di abbastanza commenti così mesi dopo puoi guardare il tuo codice, leggere il commento e riprendere da dove eri rimasto, senza troppi sforzi. Se la storia di vita del codice non è richiesta, non scriverla.

Non esiste un buon rapporto commenti / codice. Ai vecchi tempi alcune persone credevano che fosse necessario avere un commento a capo di ogni funzione che spiegasse cosa faceva.

Tuttavia, con l'avvento delle lingue moderne il codice è praticamente autodocumentante. Ciò significa che le uniche ragioni rimaste per inserire un commento nel codice sono o spiegare da dove viene una decisione strana o aiutare a comprendere un argomento davvero complicato.

Non esiste un "rapporto aureo". Dipende dalla lingua e dal modo in cui la scrivi. Più il tuo codice è espressivo, più può essere auto-documentante - e quindi meno commenti hai bisogno. Questo è un vantaggio delle interfacce fluide.

Non puoi imporre un rapporto codice / commenti fisso altrimenti finisci con un codice intriso di rumore come:

// Add one to i
i++;

che annulla solo il codice.

Osserva invece la complessità del codice e vedi cosa devi spiegare, ad es. logica squiratina, perché vengono usati determinati numeri magici, quali ipotesi sono presenti in merito ai formati in arrivo, ecc.

Attiva la mentalità dei manutentori e pensa a cosa vorresti vedere descritto riguardo al codice che hai appena scritto.

HTH.

applausi,

Rob

I commenti hanno 3 usi, IMO:

Spiega perché il codice fa quello che fa
Documenta l'interfaccia per un modulo
Spiega perché non sono stati presi altri approcci a un pezzo di logica

Se il codice sta facendo qualcosa di abbastanza semplice da chiarire il perché , che dovrebbe essere il più delle volte nella maggior parte dei domini, i commenti all'interno della logica dovrebbero essere minimi ... anche se non ci si avvicina a nessuno . I commenti non dovrebbero mai spiegare il che cosa (con possibili eccezioni per dire, ad esempio, che la funzione è un'implementazione dell'algoritmo Foo come spiegato nella pubblicazione di Bar). Se devi spiegare cosa stai facendo, lo stai facendo male.

C'è un'eccellente discussione dei commenti sul codice nel libro di Steve McConnells () Codice completo (ho la prima edizione ma credo sia ora una seconda edizione testo del link )

In breve, rinforza ciò che hanno affermato le altre risposte - dovrebbe essere raro e descrivere il perché non il come - se è possibile riformattare i nomi delle variabili e dei metodi per sostituire i commenti, allora quello dovrebbe essere prefferrato - con la maggior parte degli IDE che offrono un qualche tipo di intellisense ( o come ho sentito una volta Don Box descriverlo come - intellicrack a causa della sua dipendenza) non c'è motivo di troncare i nomi di variabili / metodi quando una versione più lunga e più chiara comunica il suo intento in modo più chiaro

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

un implicito " Fai quello che intendo " comando con un " nessun commento " commento?

Non esiste un rapporto del genere.

Di solito, i commenti dovrebbero essere presenti solo in situazioni in cui qualcosa potrebbe essere davvero poco chiaro, come

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

D'altra parte, se vendi il codice a qualcuno, avrà bisogno di quanti più commenti possibili. Imaging che vende un motore 3D o qualche altro middleware di giochi che non ha commenti. Certo, anche la documentazione API ecc. È una parte importante di tale Middleware, ma anche il buon codice commentato paga. Cose come " Aggiungi 1 a i " è ancora troppo spam, ma qualcosa come " CreateDevice () verificherà prima se DirectX 10 è disponibile e tornerà al dispositivo DirectX 9 se non " ;, può essere davvero utile, anche se è banale vedere dal codice.

In genere, il codice interno è in genere molto meno commentato rispetto al codice che vendi, ma potrebbero essere applicate eccezioni.

Mi piace usare i commenti per annotare il codice che mi assicuro sia facile da leggere e abbia variabili informative. Detto questo, mi piace provare a scrivere ogni riga di codice per essere il più informativo possibile come un commento. Dovresti essere in grado di avere un'idea molto chiara di ciò che fa il codice prima di leggere i commenti o di sbagliarti.

tra il 3% e il 9,5%, più o meno

Devo dire che sono venuto qui alla ricerca di una risposta su 2 commenti per 1 riga di codice. Anche se questa è un'esagerazione è nella giusta direzione! Invece vedo persone che raccomandano di trattare commenti come tartufi o altri prodotti rari. Guardando da una prospettiva peculiare del mondo accademico, se la qualità del codice è bassa e l'uso del controllo della versione è ancora più raro dei tartufi, esorto chiunque a scrivere quanti più commenti possibile, anche contro il tuo giudizio sul fatto che il commento sia necessario al 100%.

I commenti ti rendono la vita più semplice perché è probabile che tu stia pensando, che diavolo stavo pensando quando ho scritto questo!

Autorizzato sotto: CC-BY-SA insieme a attribuzione

Non affiliato a StackOverflow