La regola del 10% del codice è ancora valida?

Non ha senso commentare l'ovvio.

Cose che vuoi commentare:

• l'intenzione dietro il tuo codice;
• qualsiasi riferimento che possa essere utile al lettore;
• eventuali ipotesi o invarianti importanti;
• qualsiasi trucco intelligente che hai usato.

Fondamentalmente, il tuo codice sta dicendo a una macchina cosa fare; i tuoi commenti dovrebbero dire al lettore che cosa intendi con il codice.

Qualunque sia l'ammontare appropriato dipende dal contesto. Prendi il programmatore vicino a te e mostra loro il tuo lavoro. Se non riescono a risolverlo in circa cinque minuti, non hai messo una documentazione adeguata.

Rispetto la regola che il codice stesso spiega cosa sta succedendo e i commenti sono lì per spiegare perché lo sto facendo in questo modo.

Scrivo commenti come se parlassi a un pubblico di altri sviluppatori di C # che stanno facendo uno sforzo per capire cosa sta succedendo, o per me stesso dopo che ho dimenticato il progetto e sono tornato su di esso. Non vorrei leggere noiose affermazioni ovvie che ripetono ciò che il codice mi dice. Vorrei vedere perché questo approccio è stato preso, o ottenere alcune informazioni su ciò che lo sviluppatore stava pensando, ecc.

Naturalmente, in alcuni complicati blocchi di codice, un buon commento che spiega cosa sta succedendo è ancora appropriato.

Indipendentemente dal fatto che l'aggiunta dell'1% o del 20% sia irrilevante, a condizione che i commenti siano utili.

Non so che sia necessario quantificarlo in quel modo ... La mia opinione sui commenti è di metterli dove qualcun altro che sta visualizzando il mio codice vorrebbe capire qualcosa che sta succedendo. Tendo a inserire molti commenti nel mio codice, ma dove ha senso farlo. Non penso che tu possa dire il 10% o il 20%, non è quanto, ma quanto è utile.

L'attività che devi fare con i commenti è dire ai futuri lettori PERCHÉ fai le cose come fai tu. Il HOW viene detto dal codice effettivo, ma c'è un limite a ciò che puoi dire.

Ad esempio, i candidati migliori per i commenti sono PERCHÉ hai scelto di implementare una specifica routine di ordinamento invece di utilizzare solo quella nella libreria di runtime. Potresti sapere che la routine swap-element è molto, molto lenta (forse perché funziona direttamente sui supporti di memorizzazione), quindi hai scelto un algoritmo che legge tutti gli elementi, capisce dove vanno e scambia ognuno di loro esattamente una volta nella loro posizione giusta, forse anche nell'ordine giusto per ridurre al minimo l'accesso al disco. Questa è un'informazione importante e i futuri manutentori devono saperlo. Un commento - anche piccolo - dirà loro che c'è una buona ragione per essere così.

Questo implica che più il tuo codice può essere raccontato - che è uno dei vantaggi del refactoring - meno commenti devi fare. Ciò significa nuovamente che la quantità di commenti dipende dal codice, quindi non è possibile fornire numeri assoluti.

La mia regola empirica è "Come vorrei realmente sapere quando guardo questo codice tra un anno o due?" e poi aggiungilo. Altre ancora.

Se un commento è ridondante, non vale la pena scriverlo.

C # consente allo sviluppatore di scrivere codice che spiega se stesso. Quasi ogni volta che scrivo codice che deve essere completamente commentato e investo molto tempo commentandolo, due ore dopo mi ritrovo a rifare il tutto e sostituirlo con una soluzione auto-esplicativa migliore.

Non so circa il 10%. Quando stavo sviluppando per un sistema critico in C, i commenti occupavano il 30-50% del codice. In C # di solito commento solo i metodi (solo se il loro nome non implica interamente quello che fanno) e gli algoritmi. E se i metodi sono brevi (meno di 10 righe), puoi dire che i commenti occupano il 10% del codice.

Cerco di scrivere codice abbastanza chiaro che di solito i commenti incorporati non sono necessari. Ad ogni modo tengo i miei metodi brevi e uso una docstring, e questo è sufficiente per mantenere i miei commenti / code rate ben superiori al 10% (direi che hanno circa la stessa lunghezza).

Se intendi i commenti in linea, la risposta è "dipende" ... Dipende da cosa sta facendo il codice e da quanto sia complesso o non intuitivo. Inoltre, se per qualche motivo stai scrivendo un codice che sembra strano, ad esempio per aggirare un bug in un altro sistema o per rispettare un'API oscura, dovresti commentare.

La risposta in realtà non dipende dalla tua lingua o piattaforma, puoi scrivere codice leggibile nella maggior parte delle lingue (forse non tutti :-) - link potrebbe essere NSFW!) ma ci saranno comunque situazioni in cui il commento è appropriato.

Tuttavia, ciò non ha alcuna influenza sui commenti della documentazione su classi e metodi pubblici. A mio avviso, questi sono sempre necessari se non si ha il desiderio masochista di scrivere la documentazione dell'API in un documento separato. Questi commenti dovrebbero essere sufficienti per spiegare la funzionalità del tuo codice a qualsiasi client della tua API o manutentore del tuo codice, e nel caso di C # possono essere facilmente estratti per produrre documenti.

A proposito, da dove hai preso la tua cifra del 10%? Non sono familair con quel numero.