Altri commenti sono migliori negli ambienti con fatturato elevato?

Stavo parlando con un collega oggi. Lavoriamo sul codice per due diversi progetti. Nel mio caso, sono l'unica persona che lavora sul mio codice; nel suo caso, più persone lavorano sulla stessa base di codice, compresi gli studenti cooperativi che vanno e vengono abbastanza regolarmente (ogni 8-12 mesi). Ha detto che è liberale con i suoi commenti, mettendoli ovunque. Il suo ragionamento è che la aiuta a ricordare dove sono le cose e cosa fanno le cose poiché gran parte del codice non è stato scritto da lei e potrebbe essere cambiato da qualcuno diverso da lei. Nel frattempo, provo a ridurre al minimo i commenti nel mio codice, inserendoli solo in punti con una soluzione o bug non ovvi. Tuttavia, ho una migliore comprensione del mio codice in generale e ho un controllo più diretto su di esso.

La mia opinione in merito ai commenti dovrebbe essere minima e il codice dovrebbe raccontare la maggior parte della storia, ma anche il suo ragionamento ha un senso. Ci sono dei difetti nel suo ragionamento? Potrebbe ingombrare il codice, ma alla fine potrebbe essere molto utile se ci sono molte persone che ci lavorano nel breve e medio periodo.

I commenti non ingombrano il codice.

E quando lo fanno, bene, ogni IDE decente può nascondere / piegare i commenti. Idealmente, la storia dovrebbe essere raccontata dal codice, dal documento dei requisiti, dalla cronologia di commit e dalle unit test e non dai commenti. Tuttavia, commenti eccessivi possono danneggiare solo quando i commenti si concentrano sul come e non sul perché, tuttavia si tratta di una discussione diversa .

Penso che sia tu che il tuo collega abbiate "ragione", con la differenza, ovviamente, che lavorate da soli e lei in una squadra, che spesso include sviluppatori inesperti. Non hai una filosofia molto diversa sui commenti, ma requisiti molto diversi per comunicare il tuo codice. L'argomento "mi aiuta a ricordare" potrebbe anche derivare dal fatto che si occupa di molto più codice di te, e soprattutto di codice prodotto da persone diverse, ognuna con le proprie preferenze e stranezze personali.

Alla fine della giornata, i commenti sul codice, sebbene i loro evidenti difetti, sono il modo più semplice e veloce per comunicare il tuo codice. A seconda della composizione e dell'organizzazione del team, potrebbe anche essere l'unico modo che si applica al minimo comune denominatore. Di solito mi ritrovo a seguire la tua filosofia di commento quando lavori da solo e ad adattarmi a quello del tuo collega quando lavori in una squadra, specialmente se si tratta di un'abilità di squadra sbilanciata.

Commenti prolifici in quel tipo di ambiente stanno nascondendo un problema che dovrebbe essere risolto in un altro modo.

Codice leggibile e di qualità non dovrebbe mai aver bisogno di ulteriori commenti per spiegare cosa fa. L'unica volta per commentare è quando vuoi spiegare perché qualcosa è stato fatto in un modo particolare. E anche allora, quei commenti potrebbero essere probabilmente nei messaggi di commit del controllo del codice sorgente.

Quindi, il problema che sta risolvendo è che deve lavorare con studenti che non sanno come scrivere il loro codice in modo leggibile. Secondo me, ingombrare il codice con commenti è una soluzione debole a quel problema.

Rigorose revisioni del codice sarebbero molto più efficaci, sia nel mantenere il codice in ordine che nel migliorare quegli studenti per il futuro, sia che si trovino nella stessa azienda o altrove.

Il problema con i commenti è che tendono a non sincronizzarsi molto rapidamente con il codice. Questo significa che ci sono spesso commenti fuorvianti o fuorvianti nel codice, quindi danneggiano la leggibilità più di quanto aiutino.

L'obiettivo è rendere una base di codice facile da capire e modificare. Puoi farlo attraverso l'uso liberale dei commenti (anche se potresti riscontrare il problema con i commenti dei dati), oppure puoi scrivere codice autocompattante (il più possibile) e usare i commenti solo per spiegare il non banale "perché " domande. Entrambi gli approcci potrebbero funzionare, ma tieni presente che per modificare il codice dovrai capire il codice stesso e non solo i commenti. Quindi, mentre i commenti potrebbero aiutarti a capire il codice, alla fine probabilmente dovrai ancora capire il codice stesso. Detto questo, preferisco l'approccio al codice autocompensante. Sembra essere un modo più diretto per creare una base di codice pulita.

"Altri commenti sono migliori negli ambienti con fatturato elevato?"

Penso che potrebbero anche andare peggio:

• Autori diversi useranno stili e livelli di dettaglio diversi e saranno meno coinvolti nell'aggiornamento dei commenti di altre persone.

• L'opinione di "Cosa deve essere commentato" cambia da persona a persona.

• Continuano la pratica di scrivere codice che è difficile da leggere con i commenti per spiegarlo al contrario di un codice di facile lettura con nomi descrittivi.

• Mantenere il loro formato e coerenza diventa un lavoro in sé.

• I nuovi utenti devono imparare lo standard del "formato" prima di poter apportare modifiche rapide.

Punto 1: la chiarezza è importante in ambienti ad alto turnover

Punto 2: la verbosità non è chiarezza

L'aggiunta di commenti al codice può migliorare o meno la chiarezza; dipende dai commenti che aggiungi. E una volta raggiunta la chiarezza ottimale, ulteriori commenti peggioreranno la situazione, non miglioreranno.

Mentre i commenti sono un componente di chiarezza, la qualità del codice è un componente significativamente più importante. L'intelligenza è l'opposto della chiarezza . Se la funzione del codice non è immediatamente evidente attraverso una lettura casuale, il codice non è particolarmente chiaro e i commenti (non importa quanto siano di alta qualità i commenti) sono un sostituto scarso e inefficace del codice chiaro.

Ad esempio, riempire una bandiera nella parte alta di un campo non correlato può essere perfettamente ammissibile in determinate circostanze, e può avere molto senso dal punto di vista delle prestazioni in determinate circostanze, ma è quasi sempre una cattiva idea per quanto riguarda la chiarezza , anche se ne commenti l'inferno.

Se ti accorgi che devi spiegare in prosa cosa fa il tuo codice, prendi in considerazione uno dei seguenti: Nota che alcuni di questi possono influire sulle prestazioni, ma in alcuni casi le prestazioni potrebbero non essere importanti quanto la chiarezza.

• Migliori nomi di variabili e nomi di funzioni
• Migliore disposizione e spaziatura del codice
• Rimuovi tutti i "trucchi" che pensavi fossero una buona idea
• Codice Gruppo secondo la funzione concettuale (ad esempio il codice estratto per uno scopo specifico in una funzione in modo appropriato nome, anche se solo lo si chiama una volta)
• Utilizzare un algoritmo più diretto (condizioni permettendo)
• Utilizzare librerie ben note per funzionalità comuni

Una risposta semplificata: "Più è probabile che il tuo codice venga riletto, maggiore è l'onere di spiegare cosa stai facendo". Ciò potrebbe essere facilitando la lettura del codice, commentandolo, creando documentazione formale, seguendo gli standard di stile ... Nota che potresti essere tu a rileggere in seguito, anche se è certamente vero anche per gli altri in un ambiente ad alto turnover.

C'è un altro ottimo thread che copre se i commenti sono o meno documentazione.

I commenti sono più utili in alcuni scenari rispetto ad altri. Questo è così fondamentale che mi preoccupo di come spiegarlo in mezzo a così tante risposte che percepisco come "anti-commento".

Se il tuo codice potrebbe non essere letto per anni, i commenti sono più importanti che se hai un frequente refactoring del codice, una forte proprietà del codice e numerose revisioni del codice. Se l'applicazione è complessa e utilizza tecniche che non sono immediatamente ovvie per un osservatore competente in quella lingua, i commenti sono più importanti che se il sistema è un glorioso "Hello World". Se la base di codice non è così rigida con gli standard come potrebbe essere, i commenti sono più importanti che se si lavora con sei livelli di QA. Se stai lavorando in una squadra con otto persone che stanno imparando la lingua, i commenti sono più importanti che se la tua squadra ha otto Pulitzer di programmazione. Se hai un'applicazione tentacolare caduta in grembo,i commenti sono più importanti che se tu fossi in grado di costruirlo da zero.

Sarebbe meglio nella maggior parte di quegli scenari correggere la causa sottostante invece di aumentare l'uso dei commenti? Assolutamente. Ma a volte sei bloccato con una base di codice che ha più impronte digitali rispetto allo smartphone della città, e il modo migliore per migliorarlo è rendere le tue modifiche il più leggibili possibile e commentare il diavolo.

Al tuo problema specifico: i commenti non dovrebbero essere sparsi tanto da ingombrare il codice. Un paragrafo ben scritto nella parte superiore di una subroutine, che descrive perché esiste una funzione e forse perché utilizza tale approccio, è spesso la soluzione migliore per aiutare il programmatore successivo a orientarsi.