I commenti dovrebbero dire PERCHÉ il programma sta facendo quello che sta facendo? (opinione su un motto dell'inventore di Forth) [duplicato]

Should comments say WHY the program is doing what it is doing?

Sì inequivocabilmente. Non è necessario che ci siano molti commenti, bada bene, ma se li hai, PERCHÉ è l'unica domanda che vale la pena di rispondere al di fuori di alcuni bizzarri scenari marginali. Il ragionamento è semplice. Se leggo il tuo codice, buono o cattivo, posso vedere cosa sta facendo il programma. Non ho idea di perché . COME Raramente ha qualcosa che non so. PERCHÉ è spesso basato su cronologia, strane porzioni del dominio problematico o hack relativi a dipendenze di terze parti.

Dipende da cosa intendi per "perché".

Se intendi informazioni come requisiti di alto livello, storie degli utenti, ecc., allora no, i commenti non sono un buon posto per spiegare "perché". Un posto molto migliore sarebbero i tuoi messaggi di commit / push, che idealmente dovrebbero puntare a spiegazioni più complete nei ticket nel tuo tracker di problemi. E ovviamente puoi sempre avere un commento nel codice che punta al ticket.

Se, d'altro canto, intendi spiegazioni molto brevi di decisioni piccole ma non ovvie che hai preso nel tuo codice, allora tali commenti sarebbero appropriati. Ma è più o meno lo stesso di Chuck Moore che significa "COSA sta facendo il programma" (il "perché" è implicito).

Domande correlate:

• Guida per principianti alla stesura di commenti
• Best practice nella scrittura e nella documentazione dei commenti
• Stile e consigli del codice di commento
• Meglio avere più commenti in ambienti con fatturati elevati?
• Cosa dovrei inserire commenti durante il commit al controllo del codice sorgente?
• link
• Perché un'azienda dovrebbe sviluppare un'atmosfera che scoraggia i commenti del codice?

Sono un strong sostenitore del Principio di Responsabilità Unica che si presta bene ai nomi dei metodi che rivelano CHE COSA stanno facendo. PERCHÉ è un po 'più duro. Se l'implementazione è abbastanza complicata al punto che i commenti sono necessari per giustificare ciò che sta accadendo, allora sarà difficile contestualizzare, nel mezzo delle chiamate di esecuzione successive, perché un dato pezzo di codice è in esecuzione. La mia preferenza è lasciare il WHY alle storie degli utenti e mantenere il codice sufficientemente dettagliato da poter effettivamente commentare se stesso.

Perché può essere una domanda molto potente a cui rispondere.

Se hai problemi a risponderti da solo, probabilmente non stai pensando correttamente alla progettazione del codice e potresti dover riconsiderare la motivazione per la tua classe / funzione / qualsiasi cosa. Se puoi rispondere alla domanda perché in modo chiaro e conciso, anche la tua classe sarà probabilmente chiara e concisa.

L'essenza del consiglio è di scrivere codice sia per il compilatore che per le persone, e per non spiegare le cose che sono espresse dal codice.

La ridondanza tra codice e commenti crea problemi. Quando i due non sono d'accordo, probabilmente entrambi hanno torto. Se devi scriverlo due volte e leggerlo due volte, probabilmente qualcuno lo ha pagato due volte.

Tra le risposte, abbiamo voti bassi per spiegare come e i voti per spiegare cosa e perché. Sono d'accordo. Dove i commenti che mettono in relazione parti del codice, o forse spiegano le motivazioni che possono essere utilizzate per creare classi minime, coerenti e coerenti, sarebbero un vantaggio. Il chi e quando del codice possono essere trovati nel sistema di controllo del codice sorgente. I commenti di controllo del controllo del codice sorgente ci forniscono una comprensione e una correlazione dell'evoluzione dei sistemi verso i suoi obiettivi. Collegato con un bug tracker puoi rispondere a molte domande sul perché.

L'ambito e l'applicabilità sono buoni argomenti per i commenti. Se separiamo le preoccupazioni nel modo in cui dovremmo, dovremmo usare nomi e commenti per guidare i futuri manutentori. Programmazione per contratto, utilizzo di asserzioni e unit test sono tutti nel mix di chiarire il significato e il comportamento atteso del nostro software.

Il codice stesso è in parte per computer, in parte per gli umani (i nomi di metodi e variabili). Ma i commenti sono esclusivamente per gli esseri umani, sia per l'altra persona che per te stesso in futuro (chi sarà una persona leggermente diversa da te in questo momento a causa delle proprietà della nostra memoria). Qualsiasi messaggio per gli umani è prezioso se consiste in informazioni utili. Se spieghi PERCHÉ stai usando una lista ordinata e non l'hash, allora è meno probabile che ti affretti a sostituire il codice inefficace due anni dopo solo perché vedi immediatamente questa opportunità

I commenti dovrebbero spiegare aspetti del codice che non saranno immediatamente evidenti a un programmatore che abbia familiarità con la lingua. Le strutture fornite dalla lingua dovrebbero quindi essere utilizzate per ridurre al minimo il numero di commenti che rimangono necessari.

Sarò fiammeggiato per questo, ma nella mia esperienza, la maggior parte delle volte la risposta è NO .

Spunti di riflessione:

• Stai scrivendo un tema. Scrivi un paragrafo di testo. Scriveresti quindi un altro paragrafo che spiega di cosa tratta il primo paragrafo? Improbabile. La programmazione è molto diversa dalla scrittura di saggi o romanzi? Alcuni scrittori (programmatori) sono bravi e altri cattivi. Gli autori di libri scrivono per le persone, quando i programmatori scrivono per persone e macchine. Direi che il codice è scritto sia per le persone che per le macchine, quindi la maggior parte delle volte non dovrebbe esserci bisogno di commentare (descrivere) cosa fa.

• I commenti che scrivi sono sempre utili e comprensibili, vero? Che ne dici di commenti scritti dai tuoi colleghi? Cosa pensi che pensano dei commenti che scrivi? Odio alcuni dei commenti dei miei colleghi. Scommetto che anche loro non sono affezionati al mio. Bene, ho smesso di commentare tutto.

• Potresti non refactoring (rinominare, ristrutturare, riutilizzare e qualsiasi altra cosa che devi fare) il tuo codice in un modo tale che non abbia bisogno di commenti? Il più delle volte puoi farlo. In caso contrario, inserisci alcuni frammenti di codice nei commenti o nella tua risposta: sarebbe interessante per la comunità cercare di ridefinirlo in modo che non ci fosse bisogno di ulteriori commenti.

• Ti piace il mantenimento di cose inutili? Io non. La maggior parte dei commenti che ho visto in API non pubbliche non erano necessari.

• Spesso le persone commentano qualcosa che è rotto. È rotto. La classe è un disastro, fa dieci cose diverse. Lo commenterò e mi farà sentire meno colpevole. Ogni volta che qualcosa si rompe, le persone guarderanno il mio commento e questo farà sentire meglio. No, non lo farà. Il codice errato deve essere corretto su un punto, non commentato. Se non lo fai subito, più tardi ti perseguiterà o i tuoi colleghi. Indovina cosa penseranno di te?

Sono stato un ingegnere del software per alcuni anni e sono passato da "commentare tutto" a "nessun commento". Detto questo, vorrei:

• Commenta API pubbliche o qualsiasi parte di codice che verrà fornita a una terza parte, altrimenti probabilmente ti invieranno spam con reclami e richieste di supporto.
• Espressioni regolari.
• Qualcosa che è davvero complesso. Con tutti i framework là fuori, difficilmente riesco a trovare qualcosa di veramente complesso.

Una delle risposte qui afferma che senza commenti è facile vedere cosa sta facendo il programma, al contrario del perché lo sta facendo. Perché qualcosa viene fatto non appartiene al codice. Dovrebbe essere in un documento separato, SharePoint, blog, tovagliolo, ma non nel codice.