Eventuali duplicati:
Commenting codeDovremmo scrivere commenti ampiamente?
C# è un linguaggio di alto livello e in questi giorni ho incontrato codice che ha meno commenti rispetto al codice scritto qualche anno fa. Dovremmo davvero commentare un codice in grande misura? Voglio solo conoscere pensieri da voi persone.
C'è un intero capitolo dedicato ai commenti nell'eccellente libro di Robert C Martin Clean Code.
Alcuni punti salienti:
Vivo secondo 1 regola; non commentare il codice ovvio.
Cerco anche di scrivere il codice così evidente come possibile, quindi un enorme mancanza di commenti nel mio codice :)
+1 i commenti inutili nascondono anche quelli utili. –
seguo due regole ... 1) solo commento codice ingannevole 2) evitare di scrivere codice complicato a meno che sia necessario –
Dai giorni precedenti di calcolo, non commento tutto, per esempio:
if(a == 3) { // if a equals three, then...
cout << "a is three" << endl; // output "a is three" and a newline
} // otherwise don't print anything
a++; // increment a
I commenti dovrebbero avere un senso soprattutto. È buona norma fornire un'intestazione di commento su ogni funzione o classe, ma non commentare ogni singola riga.
Non è necessariamente la quantità di commenti che si desidera, ma la qualità. I commenti dovrebbero aggiungere comprensione al codice.
C# hanno entrambi uno stile di codifica imperativo (per (ciascuno), mentre ecc.) E uno stile dichiarativo (LINQ, query).
Lo stile dichiarativo è molto più leggibile e necessita di meno commenti secondo me. Tutti possono vedere che cosa questo codice di fare:
var males = from person in persons
where person.Gender == Gender.Male
select person;
Ma con una versione for(each) ciclo non può essere che visibile (per qualcosa di più avanzato forse) e commenti è necessario.
=
commento quando il codice is'nt chiaro per gli altri (e voi).
La sintassi lambda è ancora più evidente: 'var maschi = elements.Where (e => e.Gender == Sesso .Male); ' – cjk
@ck - Passare dalla sintassi procedurale a quella dichiarativa in lambda è una progressione nell'aumentare la sofisticazione del linguaggio. Se la media ** programmatore di manutenzione ** rimane "media", allora direi che i metodi più sofisticati potrebbero effettivamente richiedere più spiegazioni per loro piuttosto che meno. Ad esempio, senza conoscere LINQ è possibile seguire facilmente l'esempio di lasseespeholt in quanto così dettagliato. Ma nel tuo esempio senza conoscere la sintassi lambda, devo chiedere cosa sia "e" e cosa sia "=>" e come si relazionano. È tutta una questione su chi sia il target di riferimento per i tuoi commenti. –
Il mio suggerimento è di scrivere commenti in uno schema utile, in modo tale che i commenti siano leggibili da programmi che generano documentazione come Doxygen. Ciò ridurrà molto tempo per scrivere la documentazione.
1.) scrivere codice che non deve essere commentato
2.) se si ha realmente bisogno di un commento questo è spesso un codice di odore - forse si può cambiare qualcosa e non si deve lasciare un commento, si
sono d'accordo con questo :
http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
L'esempio della radice quadrata è fallito. Se l'algoritmo fornisse le risposte sbagliate, dove inizieresti con la versione finale? La versione centrale ha documentato il fatto che è stato utilizzato il metodo Newton Raphson che avrebbe dato al programmatore di manutenzione un punto di partenza per il debug. – JeremyP
Sono d'accordo, ma potrebbe essere risolto facilmente. Penso che il principio sia valido. –
variabili autoesplicative e nomi di metodi sono molto più importanti dei commenti. Se i nomi sono buoni e l'architettura è semplice da comprendere, quasi nessun commento è necessario.
Quindi commentare solo le intestazioni e i parametri del metodo (per generare automaticamente la documentazione) e all'interno dell'implementazione solo se si tratta di un complicato algoritmo o modello di progettazione (a volte un collegamento a una carta o Wikipedia è sufficiente) o un "hack" o soluzione alternativa.
Questi complicati e parti "sporche" di codice è quello che cerco di commentare molto ampiamente, perché queste sono le parti di codice in cui gli altri (o dopo 6 mesi) solo pensare "WTF?", Quando vedendo il codice - quindi spiega perché hai fatto questo e cosa deve essere fatto per migliorare il codice. (Spesso lo sai quando si implementa un hack, ma c'è troppo meno tempo o rischio (e quindi test-effort) è troppo alto).
+1 per questo stile di commenti! – InSane
Inserire commenti che possono sembrare o non sembrare un approccio diretto. Questo significa aggiungere commenti per dire quale algoritmo stai usando (ad esempio, durante un metodo di ordinamento, potresti voler menzionare se usi l'ordinamento Bubble Sort o Merge), o nei casi in cui apporti modifiche all'algoritmo originale (ad es. un elenco non ordinato in gruppi di tre, anziché due, quando si esegue Unisci ordinamento).
Fondamentalmente, se qualcuno che osserva il tuo codice può essere confuso ed è un programmatore piuttosto competente, inserisci un commento per spiegare cosa stai facendo e perché.
Un argomento per commenti estesi è che quando programmiamo, abbiamo tutti stili e metodi diversi. Dove lavoro, due o tre di noi potrebbero condividere lo stesso progetto e se mi avessero hackerato per settimane e l'avessi consegnato, non avrebbero avuto la minima idea di dove venissi.
Tendo a commentare quando ho qualcosa da spiegare alla persona che utilizza il codice. Sanno come programmare altrimenti non guarderebbero il codice.
//check to see if variable is X
if ($variable == "x"){
return true;
}else{
return false;
}
non vorrei esagerare con questi commenti, ma se penso di avere qualcosa da spiegare, allora lo faccio
Scrivere un commento che spiegano il motivo per cui si sta facendo qualcosa, non come lo stai facendo Il codice dovrebbe essere abbastanza chiaro affinché altri possano capire come.
Vorrei poterlo revocare due volte. Il * perché * è spesso molto più importante e prezioso del * come *! –
Sì, i commenti sono molto utili, non solo per te ma anche per gli altri.
"meno commenti rispetto al codice scritto alcuni anni fa"? Che cosa? Hai delle statistiche a supporto di questo? È una tendenza? Che tipo di raccolta di dati hai fatto? Forse dovresti lasciare questa affermazione. O forse dovresti fornire esempi. –