Costringendo le persone a leggere e comprendere il codice anziché utilizzare commenti, riepiloghi delle funzioni e debugger? [duplicare]

Il codice ben scritto dovrebbe essere sufficientemente auto-documentante da non richiedere commenti che spieghino cosa fa il codice, perché è ovvio leggere il codice stesso. Ciò implica anche che tutte le funzioni e le variabili hanno nomi descrittivi, sebbene potrebbe essere necessario per imparare il gergo del problema e dei domini della soluzione.

Questo non significa che il codice ben scritto dovrebbe essere completamente privo di commenti, perché i commenti importanti sono quelli che spiegano perché un particolare, non banale, funzione / blocco / etc è implementato così com'è e perché non è stata scelta una soluzione diversa.

Il problema con i commenti che descrivono il codice stesso è che tendono ad essere obsoleti, perché il codice viene modificato per correggere un bug, ma i commenti rimangono intatti. Questo è molto meno il caso dei commenti che descrivono il ragionamento per arrivare alla soluzione corrente.

Qualcuno (attribuito a Richard C. Haven , un programmatore Delphi) una volta ha scritto:

• I principianti non commentano nulla.

• Gli addetti ai lavori commentano l'ovvio.

  myVar = myVar + 1; // add one to myVar
  
  /* This method adjusts the page margin by the appropriate device offset */
  

• I maestri commentano la ragione per non farlo in un altro modo

  /*
  
  I already tried obvious approaches A, B, and C to solve this problem.
  They didn't work for the following reasons: ...
  
  Therefore I wrote this less-than-obvious approach which works and 
  passes all unit tests.  
  
  */
  

Il tuo "programmatore senior" potrebbe essere anziano in termini di età / longevità, ma mi sembra che abbia qualche professionista che sta crescendo.

Per quanto riguarda il debug, c'è molto da dire per il codice pulito e l'uso liberale delle dichiarazioni di registrazione e / o print() . Tuttavia, usando un buon debugger, di solito riesco a trovare il problema in una piccola frazione del tempo necessario senza di esso. È uno strumento di potere. Usalo.

I want to force people to read the code. I hate debuggers for a similar reason. They are too convenient and allow you to step through dirty code with watches and breakpoints and find the so-called problem, when the real problem was that there are bugs in the code because the code has not been simplified enough.

Il tuo programmatore senior sembra avere un problema comprensibile su stile di codifica . Ha sbagliato nel modo in cui affronta il problema, però.

Entrambi i commenti e la codifica descrittiva sono essenziali: un codice ben scritto con nomi descrittivi ti dice velocemente quale codice fa ; ma i commenti ti dicono cosa deve fare il codice (e perché no, perché lo fa in un modo e non in un altro . Poi hai dei test unitari per verificare che il "contratto" "(ciò che il codice avrebbe dovuto fare ) è effettivamente soddisfatto, e lo fa automaticamente, frequentemente e senza ulteriori sforzi da parte tua.

Senza i commenti, ci vorrebbe molto tempo (o un test unitario, che a questo punto sospetto che al tuo capo piaccia anche meno dei commenti, se crede che "i bug di vengano scoperti dalle persone che leggono il codice ) prima di trovare l'errore:

// Multiply margin by a fixed amount.
page->margin += fixedMargin;

e, sì, il commento potrebbe essere sbagliato, ma ora sai che in una di queste due righe c'è un errore . Questo, oltre a un'altra utile risorsa, controllo della versione , ti consente di trovare la discrepanza in meno di 30 secondi. Verificando l'output e persino facendo un passo con un debugger potrebbe non (un valore di fixedMargin di circa 1.01 potrebbe darti risultati ambigui, per esempio).

Se il tuo mentore è dopo la semplicità (sono d'accordo con lui che è un tratto desiderabile), dovrebbe implementare un modo per controllare le metriche come complessità ciclomatica e definizione degli obiettivi di metrica. Ciò vale anche per i commenti: sono d'accordo sul fatto che non ha senso documentare ogni singola riga di codice, ma dovresti cercare di coprire moduli, funzioni e qualsiasi "punto WTF" nel codice.

// Useless comment: multiply a by four

// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;

Il suo metodo può dare risultati - nel caso in cui odia, avresti il 20% di codifica e l'80% di documentazione e test. Con il suo metodo ottieni il 20% di codifica e l'80% di debug e grattacapo.

La differenza tra i due casi è, credo, nel morale delle persone e nella produttività generale. Se si documentano e simulano correttamente funzioni e moduli, un modulo può essere implementato da qualcuno che non ha bisogno di conoscere l'immagine generale , non deve studiare gli effetti collaterali in uno scenario di scatola nera e in fondo, può essere meno esperto .

Il tuo mentore è apparentemente a suo agio con una quantità spaventosa di debito tecnico . Controllerei le sue statistiche sullo slittamento delle scadenze e / o sugli ETA; a meno di un miracolo, qualsiasi progetto a lungo termine non mantenuto da una banda di un solo uomo o da un gruppo di compagni di codifica strettamente associato dovrebbe prima o poi richiedere il proprio debito tecnico.

Se puoi solo "leggere il codice", non avrai un'idea di quale sia la funzione che si intende fare . Quindi, se qualcuno scopa (so che nessuno lo fa, questo è un caso ipotetico) e fa qualcosa di sbagliato, non hai modo di verificarlo nel codice. Devi attendere i test unitari per rilevarlo (se lo controllano).

Aggiungete a ciò che non aggiungere commenti mi obbliga a leggere le funzioni A1, A2, A3 ... dall'inizio alla fine mentre sono interessato solo a capire la funzione A, che chiama tutto quanto sopra.

Scommetto che il tuo programmatore anziano è pigro (cattivo) o vuole che le persone notino quanto intelligente codifica (molto peggio).

If you put in comments, people won't read the code as much. Then bugs don't get caught, and people don't understand the quirks, bottlenecks, etc. of the system. That's provided the comments are actually updated with code changes, which is of course totally unguaranteed.

Niente come un idiota supponente.

La prossima volta che stai acquistando un libro da leggere. Leggere per leggerlo coprire per coprire prima di acquistarlo. Altrimenti non saprai mai esattamente se è quello che stavi cercando di comprare. Questo è praticamente ciò che ti sta dicendo di fare.

Ha fatto alcune supposizioni che sono sciocche.

1. La lettura del codice sorgente ti fornirà la prospettiva purista di ciò che fa.
2. I commenti riguardano il scope del codice sorgente a cui sono associati.

Questa è la sua prospettiva ristretta sui commenti, e come tale non vede alcun valore in essi. Ecco i limiti di non avere commenti.

1. Il codice sorgente è un set di istruzioni per un computer. Non esprime concetti o idee. Pertanto, il codice sorgente non ti dirà mai quali erano gli obiettivi dei programmatori. Il codice sorgente che compila senza errori e non si arresta in modo anomalo non riesce ancora a raggiungere gli obiettivi. Come saprai qualcosa di diverso dal computer leggendo il codice sorgente? Il computer lo fa già, ma potrebbe ancora non riuscire a raggiungere l'obiettivo.
2. Il codice sorgente non spiega l'intento del programmatore. open window, prompt for deposit non spiega che il programmatore intendeva comunicare un avvertimento all'utente.

La prossima volta che hai una conversazione con questo ragazzo e ti chiede perché stai aggiungendo commenti al tuo codice sorgente. Rispondi con questa affermazione.

"I write source code to tell the computer what to do, and I write comments to tell people what to do."

I commenti dovrebbero essere usati come una registrazione scritta che spiega qualcosa di confuso. Se stai scrivendo qualcosa che è potenzialmente confuso e non può essere semplificato, tale che sospetti che anche tu abbia difficoltà a comprenderlo sei mesi dopo, quindi scrivi un commento.

Se commenta liberamente, tutto e ovunque, i commenti perdono la loro efficacia nel segnalare le difficoltà. (Ricorda la favola del ragazzo che gridava "Lupo!")

I commenti occupano "schermo immobiliare", a meno che tu non abbia un buon editor di piegatura; devi continuare a saltare oltre quando ti muovi nel codice. E, naturalmente, commenti come /* increment i by one */ accanto a i++ sono spazzatura completa.

Se il codice è così complicato da richiedere una guida per gli interni, allora, per favore, scrivi una guida agli interni. Chiamalo README-internals.txt (o forse HTML) e mettilo nella stessa directory del codice e inserisci un commento che dice /* this is all explained in README-internals.txt */ .

Informazioni sui debugger: qualsiasi strumento che aiuti a trovare un bug è prezioso. È sciocco liquidare gli strumenti. I debugger di breakpoint non dovrebbero essere utilizzati per verificare che il codice funzioni. Almeno, non invocato come mezzo principale. Un debugger passerà allegramente un'istruzione come a[i] = i++ in C e confermerà una cattiva intuizione.

Gli strumenti di debug che effettivamente catturano una sorta di violazione in fase di esecuzione, tuttavia, possono essere considerati come uno strumento di test. Se si dispone di un debugger che rileva gli abusi della memoria dinamica e il codice supera numerosi test case in tale debugger, è una fonte di sicurezza che la memoria non viene utilizzata in modo errato.

Quindi, tieni presente che "debugger" si riferisce a più di un tipo di strumento, non solo un debugger di breakpoint / step. Alcuni debugger forniscono solo una vista del programma, lasciandoti fare il ragionamento su ciò che è sbagliato, mentre altri debugger cercano problemi per te.

Il codice non può sempre essere semplificato per non avere un debugger o rifiutare di usarne uno. Cosa succede se segui il suggerimento del tuo capo e semplifica il codice al punto che non può essere ulteriormente semplificato, e hai ancora bisogno di un debugger?

Trovo che la revisione del codice sia un processo fantastico per rispondere a questa domanda in modi concreti. Se leggo la richiesta di pull di qualcuno (mettendo in atto uno sforzo reale per leggerlo, non solo guardandolo con l'atteggiamento che tutto deve essere immediatamente evidente) e non riesco a capire cosa fa, dico alle persone di aggiungere un commento. Oppure puoi farlo da solo con un'anatra di gomma.

La maggior parte delle persone non sa esattamente quali idee devono essere commentate - È tutto ciò che diresti a qualcuno che ti sta accanto se ti hanno fatto una domanda sul codice. Spesso chiederò a qualcuno di spiegare qualcosa in una recensione, daranno un'ottima risposta, e la mia risposta è "Copia quella spiegazione che hai appena scritto in un commento nel codice."

Ma per qualche motivo questo è raramente il contenuto che le persone finiscono per scrivere nei loro commenti. Invece le persone scrivono cose inane come

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

e

// increment i by 1
i += 1

e questo è il tipo di cose a cui i colleghi esperti stanno reagendo. Io stesso dico alle persone quando sto rivedendo il codice per rimuovere questo tipo di commenti di basso livello che non aggiungono più informazioni di quelle che si possono trovare nelle righe immediatamente circostanti.

Un primo esempio di una cosa banale che fa deve essere commentato è la descrizione dei tipi di anatra in lingue dinamiche. Se l'argomento o il valore restituito di una funzione è un dict con un gruppo di proprietà su di esso, in seguito ti verrà in mente una pazzia se non commenterai esattamente quali sono quelle proprietà.

Nessuna quantità di commenti aumenterà qualsiasi codice non banale al livello che un bambino di 8 anni potrebbe capire, quindi non dovresti provare. Devi fare delle alcune ipotesi che il lettore sappia leggere il codice, perché altrimenti è uno sforzo completamente inutile.

Infine, i commenti sono molto spesso sbagliati. Le persone spesso saltano su di loro durante la lettura e non le aggiornano quando le cose cambiano. Non puoi scrivere un test unitario per i tuoi commenti, quindi solo il modo di difendere il tuo codice contro il marciume che si verifica quando i tuoi colleghi disattenti iniziano a monkeying con esso è di commentare solo le idee sono essenziali. I commenti che non aggiungono valore aggiungono un valore negativo quando diventano errati.

Design del documento, idee, architettura, storia, logica - non linee di codice.

In un mondo perfetto senza scadenze il suo approccio potrebbe funzionare.

A user reported a bug in application X. We'll let the new guy spend two months to get a deep and thorough understanding of the code, and then maybe add a few weeks of refactoring. If the bug still occurs, he should be able to find it then and won't even need a debugger!

Nel mondo reale, questo sembra un modo affidabile per uscire dal mercato.

Esempio di commento negativo

foo(); //calling function foo

Buon commento

foo(); // must call function foo, because of a bug {link to bug}

Code Complete, il lavoro fondamentale sullo stile di codifica, dedica diverse sezioni (a partire dal 19.3 in edizione 1) alla domanda dei commenti: il buono, il brutto e il cattivo. Quindi tu, e il tuo sviluppatore senior, probabilmente dovresti dare un'occhiata lì.

Detto questo, i commenti ben scritti e ben posizionati sono molto importanti per l'IMO, per qualsiasi progetto su larga scala / a lungo termine.

In un mondo perfetto, è vero che i commenti non sarebbero importanti . Ma a meno che tu non abbia una memoria fotografica e tutti quelli che lavorano sul tuo codice sono geniali, i buoni commenti aiutano a capire il codice molto più velocemente quando devi tornare indietro di un anno o due dopo e modificarlo, o qualcun altro eredita il tuo codice. (Sto dicendo che ho lavorato professionalmente per 20 anni e ben 5 o 7 anni in un progetto con diversi sviluppatori coinvolti)

Alcuni anni fa ho ereditato una complessa applicazione che ha portato a termine il lavoro ma soffre di un'architettura scadente e di uno stile di codifica incoerente e gonfio. Fortunatamente, il codice è abbastanza ben commentato, il che mi ha permesso di risparmiare giorni e settimane con la base di codice.

Un'altra cosa che mi ha aiutato ad andare più veloce è stato il debugger che uso. Quando vado ad analizzare un nuovo software su cui devo lavorare, una delle prime cose che faccio è esaminare tutti i menu, effettuare selezioni non valide o strane e vedere se riesco a rompere l'app. Quando lo interrompo, eseguo lo scenario con il debugger e vedo dove questo errore mi porta. Quasi invariabilmente questo mi porta a moduli e giunzioni importanti nel codice base: un modo rapido per trovare i luoghi importanti sulla mappa.

Anche se con il mio codice in genere non devo usare molto il debugger, ci sono occasioni in cui aiuta: nessuno è perfetto, anche se sono meticolosi sui test unitari (che è spesso impossibile quando hai ereditato codice legacy strettamente accoppiato.) E se utilizzo un nuovo modulo o componente, il debugger mi aiuta a trovare rapidamente gli errori e le incomprensioni che devo affrontare per aiutarmi ad essere aggiornato con le nuove cose.

In breve: il tempo è denaro e la maggior parte di noi programma per fornire prodotti e pagare le bollette . Seduto per settimane intere attraverso centinaia di righe di codice per trovare un bug che il debugger rivelerebbe in 10 secondi, o un codice scritto male che potrebbe essere illuminato da alcuni buoni commenti, non aiuterà molto la linea di fondo ....

Il tuo sviluppatore senior apparentemente non si preoccupa dell'efficienza e preferirebbe che gli sviluppatori passassero ore e giorni a complicare il codice complesso, quando alcuni commenti avrebbero salvato la situazione. Lo stesso vale per le sue idee sul debugging. (Solo curioso: lo sviluppatore senior usa un IDE? Perché non scrivere semplicemente tutto in un file di testo e fare una compilazione e un collegamento dalla riga di comando, ecc? Quale modo migliore per capire ogni singola riga di codice ...)

The comments don't say anything other than what the guy thought the code does at the time he put in the comment

Sai, è un approccio estremamente teorico. Non mi sorprenderebbe, se fosse stato detto dal matematico teorico, ma nei suoni di uno sviluppatore senior non suonerebbe come se fosse qualcuno con una pratica molto lunga.

Beh, teoricamente puoi analizzare il codice in testa, ma funziona solo con programmi molto semplici. Con quelli più complessi e reali, si incontra il problema di interruzione , che è uno dei problemi più complessi nella teoria del calcolo. Se qualcuno dice che può analizzare i programmi in testa, probabilmente può fare la decodifica RSA in memoria:)

Sembra che il tuo sviluppatore senior non abbia esperienza di vita reale con problemi complessi o stia cercando di impressionarti con trucchi presi dal film Hacker , o che voglia giustificare il proprio pigrizia quando si tratta di scrivere commenti.

I commenti sono per chi , quando , perché , presupposti , dipendenze e possibilmente come .

Chi ha scritto questo? Chi devo andare e bug se ho delle domande al riguardo?

Quando l'hanno scritto?

Perché l'hanno scritto? Qual è stato il motivo per cui hanno speso tempo a scrivere il codice?

Perché hanno scelto questo approccio e quali altri approcci hanno respinto e perché?

Quali ipotesi hanno fatto? Che credenze sull'organizzazione avevano?

Quali sono le cose che devono succedere perché questo codice venga eseguito con successo? Su quali librerie, oggetti, ambienti o altre cose dipende?

Quali sono le situazioni in cui il codice potrebbe non riuscire e in che modo il codice gestisce questi errori? Come faccio a gestirli?

Per quanto riguarda il "come", i commenti dovrebbero solo spiegare come funziona il codice se è complicato e difficile da capire (e se è così forse il programmatore dovrebbe aver fatto più sforzi per semplificarlo).

Ciò a cui il tuo sviluppatore senior fa riferimento è l'entropia del codice. Immagino che si riferisca a casi in cui il codice è mal progettato, e l'unico modo per comprenderlo bene e lavorare con esso sono commenti e debugger.

In altre parole, commenti e debugger possono essere utilizzati per aggirare problemi sottostanti. Tuttavia, sono entrambi strumenti e incolpare lo strumento non è un modo efficace per fare qualsiasi cosa.

Per il tuo esempio, se un codebase ha un sacco di codice non funzionante, la soluzione non deve lasciare commenti e far leggere a tutti il maggior numero possibile di codice. In realtà, questo è uno spreco di tempo e risorse. Invece, impostare processi come peer review e pair programming, dove il codice scritto da una persona è sicuro che sia stato rivisto da un altro. Questi processi non solo raggiungono lo stesso obiettivo con una maggiore precisione, ma evitano anche uno spreco di risorse in cui dozzine di sviluppatori devono comprendere un bit complesso di codice, solo perché manca di commenti e documentazione.

Inoltre, i commenti efficienti possono effettivamente ridurre la quantità di errori nel codice. La loro lettura rende il codice sorgente più facile da capire e spesso ti evita di dover cercare attraverso interi batch di file sorgente, solo per scoprire perché è necessaria una riga di codice. Certo, il commento potrebbe rivelarsi sbagliato - Ma a meno che la qualità complessiva del progetto sia davvero orribile, finirai per risparmiare più tempo affidandoti a commenti accurati, che perderai per quelli obsoleti. E risparmia tempo nella comprensione, significa più tempo per il refactoring, che è un modo molto migliore per combattere l'entropia del codice.

Scrivo codice per circa 30 anni e potrei aver detto qualcosa di molto simile a quello che ha detto quel programmatore senior. Sono anche molto consapevole dei problemi di manutenzione.

Ancora credo che alcuni punti molto importanti siano stati dimenticati nelle risposte di cui sopra:

Ho test di unità per la maggior parte del mio codice. Non è vero?

Il perché delle funzioni (l'intento dietro il codice) viene solitamente espresso attraverso test e se i test da soli non sono sufficienti vengono commentati, a volte molto pesantemente (se qualcuno di voi ha sentito parlare di programmazione di litterate potrebbero capire di cosa sto parlando)

I commenti opposti nel mio codice sono molto scarsi, quasi inesistenti, tranne che per due casi speciali: - Se ciò che viene implementato se si seguono alcuni riferimenti normativi (come le implementazioni dei protocolli di rete, su cosa sto lavorando attualmente) di solito metto il riferimento come commento sopra il codice. - Uso anche commenti per evitare di interrompere il flusso di programmazione. Inserisco commenti come: questo o quell'aspetto sbagliato, sistemalo più tardi quando codifico alcune funzionalità non correlate. Questi sono commenti a breve termine (come gli avvertimenti definiti dal programmatore) e dovrebbero essere corretti in seguito.

La mia logica per farlo è che i commenti nel codice possono essere fuorvianti. Puoi facilmente leggere un commento e credere che il codice esegua ciò che il commento finge, anche se non è vero.

Quando i commenti sul codice sono in fase di test, le cose sono diverse. Spiega come il codice dovrebbe essere chiamato e il test assicura che lo faccia effettivamente.

Di solito non uso molto i debugger. Li tengo per alcuni casi speciali (soprattutto quando non capisco cosa fa il codice, come strani bug hardware).

Ciò è cambiato con il tempo. 30 anni fa ho usato pesantemente i debugger. Quello che ho osservato è che la ricerca di bachi è di solito molto più lenta di altri metodi. Quello che di solito faccio ora è individuare i bug nei test unitari, prima erano i migliori. Questo ha l'ulteriore vantaggio di dare un test di non regressione. Mai morso due volte dallo stesso bug.

Ero solito commentare molto, ora pochissimo, rendere leggibile il codice ei nomi delle variabili è la strada da percorrere.
Aggiungo commenti per veri "trucchi" e "perché è stato fatto ciò che non è (ancora) ovvio dal codice".

Ma per la tua vera domanda.

Ho notato che il tuo titolo inizia con la parola: "forzatura"

Ho anche notato che il primo paragrafo menziona "confrontarsi"

Ho usato esattamente le stesse parole 20 anni fa:)

Questo (IMHO ovviamente) è ciò che riguarda realmente la programmazione: in che modo persone diverse con stili, opinioni, esperienze, conoscenze e background diversi possono lavorare insieme.

Non esiste una soluzione semplice, nessuna lista di passi programmatici da intraprendere, nessuna conversazione per sistemare le cose. Consiglierei di pensare ai seguenti punti che ho appreso dalla mia esperienza di 20 anni.

1. Ascolta
2. Ascolta
3. Ascolta. Mi spiace farne un grande affare, ma nulla ti aiuterà di più nella tua carriera ora di fare domande e ascoltare anche se la risposta non ha senso.
4. Fai domande e ascolta le risposte anche se non sei d'accordo o non le capisci completamente. C'è quasi sempre una seconda possibilità di rivisitare le cose.
5. Accettate che a volte le cose si possano fare. Se sono davvero pessime decisioni che continueranno a mostrare e si può fare un caso più tardi per renderle migliori. Ma l'enfasi sul dopo. Abbastanza buono per ora è qualcosa che devi accettare a volte in modo da poter fare di più per ora.
6. Scegli le tue battaglie su cose che non vanno. Impara a tenere la lingua a meno che l'oggetto sia davvero molto importante per te e anche allora scegli le battaglie con molta attenzione e prova a fare le conversazioni e non le battaglie!
7. Accetta le differenze. Al di fuori del mondo accademico dovrai accettare più differenze e concentrarti (poco) meno sul trovare il modo "corretto e vero" di fare le cose e altro su ciò che funziona per oggi e per il business in cui lavori.
8. Evita conversazioni in bianco e nero. Non essere assolutista della "cosa giusta" evita parole assolutiste come "must", "solo", "impossibile", ecc. E usa parole come "dovrebbe" "spesso" e "duro".
9. Utilizza esempi concreti in conversazione piuttosto che in teoria. Non evitare la teoria, ma nelle conversazioni cerca di avere esempi reali per i tuoi punti. Se non hai esempi reali, questo potrebbe essere un indicatore del fatto che dovresti elencare più che parlare.
10. Enfatizza la tua giovinezza e l'ignoranza nelle conversazioni con programmatori più esperti come quello che menzioni. Li impressionerai di più con umiltà che vantarti delle tue conoscenze acquisite di recente.

I commenti sono molto sopravvalutati e spesso usati impropriamente. Sebbene non conosca la tua situazione attuale (poiché non trovo la citazione citata che parli di buona leggibilità del codice), in generale non dovresti spruzzare commenti su tutto il tuo codice (con forse l'eccezione dei commenti di alto livello, che sono già vicino a documentation0.

È per un motivo che il commento è uno degli odori di codice descritti nel libro di Rifattorizzazione di Martin Fowlers (per un sommario, vedi: link , il libro non è liberamente disponibile afaik).

Tuttavia, dovresti sostituire i commenti con metodi e nomi di variabili significativi, e non penso che w e gs classificano. Tuttavia, personalmente preme di più sul buon naming, che sul commentare.

Btw, se cerchi "codice pulito" e "commenti" o "odore di codice" e "commenti" trovi ottime letture su questo, es. link (con una sintesi del motivo per cui Zio Bob Martin di Clean Code non gradisce i commenti)

Ogni volta che scrivi codice, dovresti pensare al prossimo programmatore che erediterà ciò che hai scritto. Se scrivi commenti perché ti è stato insegnato a farlo come best practice o solo per abitudine, dovresti probabilmente smettere di scrivere commenti in ogni momento perché chiunque legga le tue cose inizierà a ignorarle come inutili.

Se commentate solo quando nominare le convenzioni e la struttura non è in grado di spiegare alcuni elementi bizzarri di ciò che state facendo (di solito a causa di qualcos'altro in un codebase che è completamente batshit), prenderanno in considerazione ciò. Se stai contrassegnando bit di codice problematici, per gridare ad alta voce mettici una data su di esso in modo che sia più facile rivedere le modifiche che hanno portato alla shenanigans nel controllo del codice sorgente.

Riguardo ai debugger, posso sentire un pizzico di solidarietà sul tipo (sto supponendo) della vecchia scuola, principalmente procedurale perché vengo da JavaScript che ricomincia quando tutto ciò che IE ha detto che era "Oggetto non trovato". Perché hanno persino infastidito, non lo so, ma quando occasionalmente hai a che fare con quel genere di cose, pensi molto più difficile su come strutturare il tuo codice in modo tale che sarà molto più ovvio dove qualcosa è andato sbagliato in modo da poter diagnosticare rapidamente con la registrazione / avvisi.

Detto questo, non scambierei gli strumenti di Chrome Dev o Firebug per qualcosa che non fosse una scatola della polizia di Time-Traveling. Ma il punto, penso, è questo. Se la prima cosa che fai è avviare una traccia nel debugger senza nemmeno guardare il codice che è coinvolto, potresti non strutturare il tuo codice come meglio potresti. Cerca sempre di essere diretto, ovvio, minimalista e facile da leggere come se non esistesse IDE o debugger per aiutarti. Inizia guardando il tuo codice quando fai un primo tentativo. Se non è facile neanche immaginare dove le cose stanno andando male, potresti voler riflettere su come scrivere codice senza strumenti moderni. La maggior parte di Java e C # che abbia mai visto non hanno alcuna conoscenza dei fondamenti di base di OOP.

I commenti nel codice sono una manna dal cielo se usati correttamente, ma come altri hanno sottolineato che sono spesso abusati. Non ho intenzione di reiterare ciò che è già stato indicato, ma dirò che dovresti solo commentare se sai che il codice che stai scrivendo è complicato e non c'è altra via percorribile.

Se ritieni di dover commentare, pensa prima al codice e chiediti; Perché stai scrivendo quel commento? C'è un altro modo di scrivere il codice che non avrebbe bisogno di un commento?

Non scrivere commenti per scrivere commenti. Commenta solo come ultima risorsa o dove aiuterà coloro che dovranno lavorare sul codice più avanti. Se ti ritrovi a scrivere commenti che descrivono cosa sta facendo una variabile, è probabile che tu stia commentando troppo. I programmatori cattivi commentano tutto, i buoni programmatori commentano solo quando necessario.

A proposito di debugger, lavoro con alcuni ingegneri che hanno seguito tutta la loro carriera senza mai licenziare un debugger. Perché? Un debugger è uno strumento come un altro. Proprio come nella maggior parte dei casi un martello a sfera farà il lavoro, a volte hai bisogno di qualcosa con più finezza.

Un debugger ha due scopi.

1. È usato per trovare bug
2. Mostra un percorso attraverso il tuo codice.

Possono essere molto utili per portare i nuovi arrivati alla velocità e possono essere ancora più utili nel tracciare quei bug molto difficili da trovare ma non sono l'unico modo e ci sono volte in cui un debugger è in realtà un ostacolo più di un aiuto.

Per quanto riguarda il riepilogo delle funzioni, beh ogni funzione dovrebbe avere un docblock, questo è un must ma non andare a renderle lunghe ed elaborate. L'estate dovrebbe essere una descrizione di 1 riga con ogni parametro chiaramente descritto.

/**
 * A getter method for foo
 *
 * @param bool $bar If true, bar will be attached to foo
 *
 * @return foo
 */

Usa solo un docblock dettagliato se esiste una causa. Se il metodo è troppo complicato allora sì, inserisci una spiegazione ma, se possibile, cerca di evitarlo. Un buon codice dovrebbe documentarsi da solo.

Ricorda che tutti amano leggere romanzi ma nessuno vuole leggere la guerra e la pace alle 9 di lunedì mattina.

I commenti sono molto utili e possono fare la differenza tra codice chiaro e codice non chiaro.

Solo perché è stato fatto in un modo "indietro nel tempo" non significa che un altro modo è inaccettabile.