Sono più commenti meglio negli ambienti ad alto turnover?

I commenti non ingombrano il codice.

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

Penso che sia tu che il tuo collega siete "giusti", con la differenza che, naturalmente, lavorate da soli e lei in una squadra, che spesso include sviluppatori senza esperienza. Non hai una filosofia tanto diversa sui commenti, ma requisiti molto diversi sulla comunicazione del tuo codice. L'argomento "mi aiuta a ricordare" potrebbe anche derivare dal fatto che si occupa di molto più codice di te e, soprattutto, codice prodotto da persone diverse, ognuna con le proprie preferenze e peculiarità personali.

Alla fine della giornata, i commenti di codice, anche se i loro difetti evidenti, sono il modo più semplice e veloce per comunicare il 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 trovo a seguire la tua filosofia di commento quando lavoro da solo e mi adeguo al tuo collega quando lavoro in una squadra, specialmente se si tratta di una squadra squilibrata.

I commenti prolifici in questo tipo di ambiente nascondono un problema che dovrebbe essere risolto in un altro modo.

Il codice di qualità e leggibile non dovrebbe mai richiedere commenti aggiuntivi per spiegare cosa fa. L'unico momento per commentare è quando vuoi spiegare perché qualcosa è stato fatto in un modo particolare. E anche allora, quei commenti potrebbero essere verosimilmente presenti nei messaggi di commit del controllo del codice sorgente.

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

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

Il problema con i commenti è che tendono a crescere molto velocemente con il codice non sincronizzato. Ciò significa che ci sono spesso commenti errati fuorvianti o espliciti nel codice, quindi danneggiano la leggibilità più di quanto possano aiutare.

L'obiettivo è di rendere una base di codice facile da capire e modificare. Puoi farlo con un uso liberale dei commenti (anche se potresti incorrere nel problema con i commenti dei dati), oppure puoi scrivere codice di auto-documentazione (il più possibile), e usare solo commenti 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 della giornata probabilmente dovrai ancora capire il codice stesso. Detto questo, preferisco l'approccio al codice di auto-documentazione. Sembra essere un modo più diretto per creare una base di codice pulita.

"Più commenti sono migliori in ambienti con fatturati elevati?"

Penso che potrebbero essere peggio:

• Diversi autori useranno stili e livelli di dettaglio diversi e saranno meno interessati ad aggiornare i commenti di altre persone.

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

• Continua la pratica di scrivere codice difficile da leggere con commenti per spiegarlo al contrario di codice di facile lettura con nomi descrittivi.

• Il mantenimento del loro formato e coerenza diventa un lavoro a sé stante.

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

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

Punto 2: Verbosità non è Chiarezza

Aggiungere commenti al tuo codice può o non può migliorare la chiarezza; dipende dai commenti che aggiungi. E una volta raggiunta la chiarezza ottimale, i commenti aggiuntivi renderanno la situazione peggiore, non migliore.

Sebbene i commenti siano un componente della 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 (indipendentemente dalla qualità dei commenti) sono un sostituto scadente e inefficace del codice chiaro.

Ad esempio, il riempimento di una bandiera nel campo di un campo non correlato può essere perfettamente consentito in determinate circostanze e può essere sensato dal punto di vista delle prestazioni in determinate circostanze, ma è quasi sempre una cattiva idea con rispetto alla chiarezza, anche se ne commentate l'inferno.

Se ti ritrovi a dover spiegare in prosa come funziona il tuo codice, considera quanto segue: Nota che alcuni di questi possono influire sulle prestazioni, ma in certi casi le prestazioni potrebbero non essere così importanti come chiarezza.

• Migliori nomi di variabili e nomi di funzioni
• Migliore layout e spaziatura del codice
• Rimuovi eventuali "trucchi" che ritieni siano una buona idea
• Raggruppa il codice in base alla funzione concettuale (ad esempio, estrai codice per uno scopo specifico in una funzione con nome appropriato, anche se lo chiami solo una volta)
• Utilizza un algoritmo più diretto (condizioni permettendo)
• Utilizza librerie note per funzionalità comuni

Una risposta eccessivamente semplificata: "Più è probabile che il codice venga riletto, maggiore è l'onere di spiegare quello che stai facendo." Ciò potrebbe essere rendendo più leggibile il codice, commentandolo, creando una documentazione formale, seguendo gli standard di stile ... Si noti che potrebbe essere tu che è facendo la rilettura più tardi, anche se è certamente vero anche per gli altri in un ambiente ad alto turnover.

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

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

Se il tuo codice potrebbe non essere letto per anni, i commenti sono più importanti di quelli che si verificano se si dispone di un frequente refactoring del codice, una strong proprietà del codice e recensioni di codice copiose. Se la tua applicazione è complessa e utilizza tecniche che non sono immediatamente evidenti per un osservatore esperto in quella lingua, i commenti sono più importanti di se il sistema è un glorificato "Hello World". Se la base di codice non è così rigida con gli standard che potrebbero essere, i commenti sono più importanti rispetto a quando lavori con sei livelli di QA. Se stai lavorando a un team con otto persone che stanno imparando la lingua, i commenti sono più importanti rispetto a quando la tua squadra ha otto Pulizer di programmazione. Se hai lanciato un programma tentacolare sulle tue ginocchia, i commenti sono più importanti di quelli che potresti riuscire a ricostruire da zero.

Sarebbe meglio nella maggior parte di questi scenari per risolvere 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 su di esso rispetto allo smartphone della città, e il modo migliore per migliorarlo è rendere le tue modifiche il più leggibili possibile e commentarne il funzionamento.

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