Ti piacciono i tuoi commenti? [chiuso]

Question

Quali sono le tue migliori pratiche per i commenti? Quando dovrebbero essere usati e cosa dovrebbero contenere? O sono necessari anche i commenti?

Answer 1

I commenti sono essenziali per la manutenibilità. Il punto più importante da ricordare è spiegare PERCHÉ stai facendo qualcosa, non COSA stai facendo.

Answer 2

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.

Answer 3

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.

Answer 4

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?

Answer 5

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.

Answer 6

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.

Answer 7

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.

Answer 8

Utilizza la ricerca tag e troverai che SO ha già un mucchio di discussioni sui commenti del codice:

https://stackoverflow.com/questions/tagged/comments

Codice di commento

Answer 9

Dai un'occhiata a Codice completo . È semplicemente il migliore per tali argomenti.