Ti piacciono i tuoi commenti? [chiuso]
-
02-07-2019 - |
Domanda
Quali sono le tue migliori pratiche per i commenti? Quando dovrebbero essere usati e cosa dovrebbero contenere? O sono necessari anche i commenti?
Soluzione
I commenti sono essenziali per la manutenibilità. Il punto più importante da ricordare è spiegare PERCHÉ stai facendo qualcosa, non COSA stai facendo.
Altri suggerimenti
A scuola, la regola era di commentare tutto, tant'è che i commenti superano il codice. Penso che sia sciocco.
Penso che i commenti dovrebbero essere usati per documentare il "perché" dietro il codice, non il "come" ... il codice stesso spiega il "come". Se c'è un'operazione che non è molto chiara sul perché venga eseguita, è un buon posto per un commento.
Talvolta TODO e FIXME vanno nei commenti, ma idealmente dovrebbero andare nella gestione del codice sorgente e negli strumenti di tracciamento dei bug.
L'unica eccezione in cui non mi dispiace commenti apparentemente inutili è per i generatori di documentazione, che stamperanno la documentazione solo per le funzioni che sono commentate - in tal caso, ogni classe pubblica e interfaccia API devono essere commentate almeno abbastanza per ottenere la documentazione generata.
Idealmente il tuo programma può comunicare con il lettore in codice e non nei commenti. La capacità di scrivere software che altri programmatori possono capire rapidamente separa i migliori programmatori dalla media secondo me. In genere, se tu o i tuoi colleghi non potete comprendere una sezione di codice senza commenti, allora si tratta di un "odore di codice" e refactoring dovrebbe essere in ordine. Tuttavia, ci saranno alcune librerie arcaiche o altre integrazioni che alcuni commenti per guidare lo sviluppatore medio non sono necessariamente negativi.
Come spesso la risposta è: dipende. Penso che il motivo per cui hai scritto un commento sia molto importante per la decisione, se il commento è positivo o negativo. Esistono diverse possibili ragioni per i commenti:
- per rendere più chiara la struttura (ovvero quale loop è terminato qui)
Cattivo: sembra un possibile odore di codice. Perché il codice è così complicato, che ha bisogno di un commento per chiarirlo?
- per spiegare cosa fa il codice
Pessimo: questo è secondo me pericoloso. Accadrà spesso che in seguito cambi il codice e dimentichi il commento. Ora il commento è sbagliato. Questo è molto male.
- per indicare una soluzione alternativa / un bugfix
Buono: a volte una soluzione a un problema sembra chiara, ma l'approccio semplice ha un problema. Se risolvi il problema, potrebbe essere utile aggiungere un commento, perché è stato scelto questo approccio. Altrimenti un altro programmatore in seguito può pensare di "ottimizzare" il codice e reintrodurre il bug. Pensa al problema Debian OpenSSL. Gli sviluppatori Debian hanno rimosso una variabile unitaria. Normalmente una variabile unitializzata è un problema, in questo caso era necessaria per casualità. Un commento in codice avrebbe contribuito a chiarirlo.
- a scopo di documentazione
Buono: parte della documentazione può essere generata da speciali commenti formattati (ad es. Javadoc). È utile documentare le API pubbliche, che è un must. È importante ricordare che la documentazione contiene l'intenzione del codice, non l'implementazione. Quindi risponde al commento alla domanda "Perché hai bisogno del metodo (e come lo usi)" o Cosa fa il metodo?
Penso che il nuovo movimento per rimuovere i commenti sia negativo ... il motivo, ci sono molti programmatori che pensano di scrivere codice facile da capire che non ha bisogno di commenti. Ma in realtà non è proprio il caso.
Quale percentuale di codice di altre persone leggi e lo capisci all'istante .. Forse ho letto troppo asp classico, Perl e C ++ ma la maggior parte delle cose che leggo è difficile da sfogliare.
Hai mai letto il codice di qualcuno e ne sei completamente confuso. Pensi che abbiano pensato mentre scrivevano, questa è una schifezza ma non mi interessa davvero. Probabilmente hanno pensato ohh ... questo è molto intelligente e sarà SUPER veloce.
Solo alcune osservazioni:
I commenti sono importanti per tutto ciò che non può essere facilmente dedotto dal codice (ad es. algoritmi matematici complessi).
Il problema con i commenti è che devono essere mantenuti come il codice ma spesso non vengono affatto mantenuti.
Non mi piacciono i commenti come questo:
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
Meglio:
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
Ora il codice racconta l'intera storia. Non è necessario un commento.
Penso che dipenda dallo scenario.
I metodi / funzioni / classi hanno bisogno di una breve descrizione di ciò che fanno, come lo fanno, cosa prendono e cosa restituiscono, se non immediatamente ovvio e che di solito (nel mio codice) si presenta sotto forma di javadoc- blocco commenti stile.
Codice in blocco, tendo a lasciare un commento sopra un blocco di linee per spiegare cosa fa, o uno alla fine della linea se si tratta di una chiamata di funzione breve e criptica.
Utilizza la ricerca tag e troverai che SO ha già un mucchio di discussioni sui commenti del codice:
Dai un'occhiata a Codice completo . È semplicemente il migliore per tali argomenti.