Perché un'azienda dovrebbe sviluppare un'atmosfera che scoraggi i commenti del codice? [duplicare]

Troppi commenti sono molto peggiori di troppo pochi. Prendono tempo per scrivere e ancora più tempo per mantenere. Durante la vita di un progetto, il codice rifletterà sempre ciò che fa il programma, i commenti saranno inaccurati nell'istante in cui il codice cambia. Una volta che l'intento del codice non corrisponde al commento, sei su una pista in discesa scivolosa. I commenti non vengono verificati dai compilatori per correttezza, quindi i commenti errati non possono essere rilevati e corretti dal programmatore, a meno che non venga fatta un'enorme quantità di attenzione ai dettagli, dove fa poca differenza.

Nella mia esperienza, i nuovi programmatori spesso sovrastano il codice con commenti inutili che non aggiungono alcun valore. Casi estremi come questo sono comuni

int x ; // Integer x 
// Copy the string bob into fred making sure not to overflow the buffer. 
strncpy(bob, fred,sizeof(bob));  

(L'errore è intenzionale per fare un punto)

Tuttavia gli sviluppatori che inseriscono troppi commenti sono altrettanto comuni ......

I commenti dovrebbero essere fatti sul codice "paragrafi". A meno che tu non abbia una fodera densa, molto raramente hai bisogno di un commento per spiegare un singolo comando. Chiunque abbia familiarità con il langauge in questione dovrebbe essere in grado di capirlo solo leggendolo o cercandolo.

Quello che stai cercando di documentare è il flusso logico del codice, non i dettagli grintosi. Ad esempio:

writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

Tutto da solo, cosa significa? Dobbiamo scavare in ogni riga di codice e metterlo insieme per comprendere che cosa sta succedendo, ma non sappiamo ancora perché. E se questo fosse più lungo, per un'idea più complicata? Confrontalo con questo:

# Dump found entries into a CSV file for Excel
writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

Chiunque lo verifichi in seguito comprende sia il contenuto che l'obiettivo di questo codice, senza la necessità di scavare e imparare cosa fa .

Il problema inizia con le persone che sono dell'opinione che i commenti spieghino cosa fa il codice . Quindi è un salto molto facile a "perché disturbare i commenti" e quindi a "non commentare qui".

Invece, i commenti dovrebbero spiegare perché esiste il codice.

/* setting foo to 1 here so that biz doesn't run too many times 
 * changed from 6 on 3-Aug-11 for ticket 1234
 */
foo = 1; 

Questo è, penso, qualcosa che dovrebbe essere (ma non lo è) spiegato a scuola.

Ho lavorato una volta in una società che scoraggiava troppo l'uso dei commenti. Anche se questo era per Ruby on Rails . Ruby è un linguaggio molto espressivo e il framework Ruby on Rails detta in modo abbastanza chiaro dove le cose appartengono e quali sono buono per. Quindi usare i commenti in un controller per spiegare a cosa serve un metodo sarebbe stato inutile. Quindi questo può dipendere dal contesto e dalla lingua che usi. Molto può essere già spiegato usando nomi descrittivi per metodi e variabili. Potrebbe persino costringerti a mantenere i metodi piccoli e avere un unico scopo ben definito. Se diventa difficile trovare un buon nome per un metodo, è molto probabile perché la cosa sta facendo troppo e dovrebbe essere divisa in parti più piccole.

Lasciare il vecchio codice e commentarlo è una cattiva abitudine. Questo è ciò per cui viene utilizzato un sistema di controllo della versione. Se vuoi vedere lo stato precedente di un file, utilizza la funzionalità di Git o SVN o qualsiasi altra cosa tu usi. Altrimenti devi scorrere pagine e pagine di vecchie cose che non hanno più senso nel contesto attuale.

I commenti sono utili ogni volta che lo scopo del codice non è immediatamente evidente.

Forse il codice potrebbe essere reso più chiaro, forse no.

Forse è ovvio per te, ma non lo sarebbe a qualcun altro.

È una sentenza .

^{(Mi sento un po 'stanco dei religiosi anti-commentatori, che spesso si avvicinano pericolosamente a buttare fuori il bambino con l'acqua sporca, potrebbero volutamente esagerare nel loro caso, avendo capito il problema, ma altri lo prenderanno a bordo e ne aggiungeranno un altro in più alla loro ignoranza. Con tutti i mezzi, combatti per ottenere un codice più chiaro, quando hai vinto quella battaglia, inizia a combattere contro i commenti.)}

Direi che dipende dalla situazione. Quando il codice non è troppo esoterico e i nomi delle variabili sono ben scelti, in modo che il codice sia "auto-documentante", i commenti potrebbero non essere necessari. Ma quando l'intento non è chiaro solo guardando il codice (ad esempio quando si usa qualche oscuro teorema matematico), allora un buon commento spiega il perché.

Ricorda che anche se non vengono compilati, i commenti devono essere mantenuti per seguire il codice. Immagina un commento che spiega la cosa sbagliata perché il codice è cambiato e lo sviluppatore non è in grado di capirlo. Quindi troppi commenti significano un lavoro più inutile. (È troppo o non è abbastanza migliore? Questo è un altro dibattito)

Per quanto riguarda il tuo caso, a volte gli altri sviluppatori devono dare un'occhiata al codice degli altri? Non hai mai sentito uno di loro (o te stesso) che ha detto "Cosa fa questo codice? Non capisco niente!". Se è il caso, forse è necessario un commento ben piazzato.

I commenti vanno bene, purché vengano utilizzati solo quando necessario e spiegano qualcosa che non è ovvio. Gli esempi di mattnz lo rendono chiaro. Non c'è nulla che non sia ovvio in quella parte del codice poiché utilizza solo funzioni già documentate. Ad esempio, eseguendo man strncpy puoi scoprire tutto su questa funzione. Non inserire commenti in tale codice è molto meglio e meno confuso per gli altri programmatori.

Documenta solo le parti complesse del tuo codice e, se necessario, l'input / output e gli argomenti delle tue funzioni / metodi; quest'ultimo è utile se si desidera esportare la propria API utilizzando un sistema di documentazione. Non dimenticare che quando una parte del codice viene aggiornata, anche i commenti devono essere aggiornati, quindi i tempi di manutenzione sono più lunghi; il che significa che i tuoi commenti dovrebbero davvero valere la pena.

Ci sono principalmente due categorie di commenti:

• Commenti che spiegano il codice
  Come altri hanno già detto, codice e commenti tendono a deviare a parte. Puoi lasciare un commento prima di un blocco di codice, ma quando il tempo passa, il codice cambia e nessuno aggiorna il commento per riflettere le modifiche. Il commento diventa una bugia.
  Se ritieni che un blocco di codice abbia bisogno di un commento per spiegare l'intenzione del codice, ciò che potresti fare, invece, è estrarre il blocco di codice in un metodo e assegnargli un nome . Il nome diventerà quindi la spiegazione. E i nomi dei metodi non vanno alla deriva allo stesso modo dei commenti. A nessuno piace chiamare un metodo chiamato 'GetData' che in realtà salva alcuni dati. O lo sviluppatore potrebbe cambiare il nome del metodo, o vedere che il cambiamento che faranno non appartiene affatto lì.
  Ci sono alcune cose che non possono far parte di un nome, però. Come perché hai scelto questo algoritmo rispetto all'altro, o perché quella che sembra una soluzione più ovvia a un problema non va bene in questo caso particolare e così via.
  Ci sono altri casi in cui un nome vuole contenere tutto quello che c'è da sapere sul codice. Se hai una buona serie di test unitari (e dovresti), la suite di test farà parte della spiegazione dell'intenzione e del funzionamento interno del codice. E nominare i tuoi test è importante quanto nominare il tuo codice di produzione.

• commenti disabilitazione codice
  Quando si scrive un nuovo codice, è spesso "confortante" mantenere il vecchio algoritmo per riferimento, dopo un po 'il codice tende ad essere ingombrato da blocchi di codice piccoli o grandi disabilitati dai commenti. Rende il codice più difficile da leggere e il lettore deve considerare se il codice è pertinente o meno .
  Non è necessario questo tipo di commenti, poiché ogni modifica di un file dovrebbe essere comunque conservata in un sistema di controllo del codice sorgente . Se hai bisogno di verificare come un algoritmo si trovava in una versione precedente, dovresti essere in grado di andare lì e dare un'occhiata. Ogni check in dovrebbe avere un commento che descriva l'intenzione del commit del codice, o un link a una segnalazione di bug o qualcosa del genere.

Robert C. Martin ha scritto un libro chiamato " Pulisci codice ". Ha dedicato un intero capitolo ai commenti in codice. Il libro è buono e vale sia soldi che tempo.

In termini generali, scriviamo software per creare o aggiungere valore.

I commenti, tuttavia, non fanno parte della parte binaria / eseguibile del software, ma fanno parte dell'aspetto del codice sorgente del software. Pertanto, si suppone che aggiungano valore al codice sorgente.

I commenti che non aggiungono valore sono inutili e sbagliati.

Quando i commenti non corrispondono a ciò che sta facendo il codice, allora il software è sbagliato e il valore è perso.

Scrivere commenti ha un costo. Se i commenti devono avere un valore netto positivo, il costo di scrittura dei commenti deve essere inferiore al valore che uno raccoglie da loro.

Tutto il resto sono solo dettagli.

Sicurezza del lavoro è un motivo valido. Se nessuno, ma tu capisci il codice, non puoi essere licenziato.

Nota a coloro che non hanno letto il sarcasmo per le persone davvero intelligenti: non commentare correttamente il codice non è professionale.

Nella mia esperienza personale, i commenti sono utili in due casi:

1. spiega il codice al programmatore successivo (se esci)
2. spiega a te stesso il codice (quando hai a che fare con migliaia di file e non riesci a ricordare la logica dietro di essi).

Il secondo punto è il più importante e per lo più trascurabile da parte di alcune aziende, pensando di aver bisogno di commenti solo nel caso 1, e se quel caso non è nei loro piani allora i commenti non sono così ..

Inoltre, non sta programmando di prendere decisioni tutte le volte? Come puoi ricordare i motivi dietro una decisione se non la annoti?

Raccomando di scrivere commenti (anche contro il flusso aziendale), perché la tua produttività dipende in qualche modo da esso.

Se la società non richiede commenti nel codice, la maggior parte dei programmatori non commenterà a causa della loro pigrizia e troveranno una scusa intelligente perché i commenti non sono mai necessari.

D'altra parte, a volte i commenti sono davvero superflui (ad esempio in getter e setter banali in Java), e se la società crea una politica di scrittura dei commenti ufficiale, i programmatori sono a rischio di essere costretti a scrivere commenti anche in tali situazioni. Un manager ambizioso può anche richiedere modelli di commento molto complicati.

Ciò si traduce in una situazione in cui alcuni programmatori scrivono commenti e maledicono silenziosamente la pigrizia dei loro colleghi, ma non rischiano di discutere apertamente di questo argomento, perché le cose potrebbero peggiorare.

I commenti sono un argomento sfuggente e sul web troverai un sacco di flamewar sulla giusta quantità di commenti che uno sviluppatore dovrebbe scrivere.

Persino a me piace mettere in relazione la necessità di commenti alla "scala di tecnicità" del codice che si desidera commentare. Su un'estremità della scala si ha un codice vicino al metallo che utilizza molti tipi primitivi, che si occupano del sistema o codice che ha subito modifiche oscure per motivi di prestazioni. L'estremo opposto della scala è il codice puramente relativo al dominio (di solito nel livello business / dominio), che a mio parere deve essere il più espressivo possibile, con nomi di classi, variabili e metodi che riflettono concetti di vita reale del proprio dominio.

Il codice tecnico di basso livello potrebbe richiedere un sacco di commenti, perché il suo scopo potrebbe essere nascosto dietro manipolazioni tecniche non ovvie, algoritmi complessi o utilizzo di tipi primitivi. Un esempio di base è se un metodo restituisce un int (che non incoraggerei, ma a volte operazioni di livello inferiore devono farlo), senza un Javadoc -come commento sul metodo non hai modo di sapere in anticipo se l'int restituito è un codice di errore, un ID ...

Viceversa, maggiore è il numero di domini che ottieni, meno commenti hai bisogno, perché i nomi degli oggetti che manipoli dovrebbero essere auto-esplicativi.

Un ulteriore pensiero: non sottovalutare la potenza dei test unitari in sostituzione dei commenti ai fini della documentazione del codice. Un test unitario ben scritto ti dice immediatamente qual è la responsabilità del metodo AND è ED eseguibile e sicuro per la compilazione.

Why would a programmer not writing comment, if there are any objective reasons?

I commenti richiedono tempo per scrivere e talvolta possono essere messi in attesa per altri lavori con priorità più alta. Non hai mai avuto casi in cui era più importante "git-r-done" che commentare cosa è stato fatto nel passato quando?

Do you think comment annoying when you read other's code?

I commenti possono essere utili ma quanti posti ti permetteranno di passare ore a scrivere commenti che non aggiungono valore commerciale immediato?

La mia opinione generale è che i commenti sono buoni con moderazione. Troppo o troppo poco può essere un grosso problema.

Vogliono che il tuo codice abbia senso in sé e per sé. Nel mondo reale, non è sempre possibile. Ma è meglio cercare il primo e trovare un modo per affrontare quest'ultimo.

Dal mio punto di vista, i commenti dovrebbero generalmente essere limitati ai commenti a livello di metodo ( Javadoc o ai commenti di tipo XML XML) per la generazione della documentazione più tardi e i commenti di TODO. Oltre a ciò, penso che nella maggior parte dei casi i commenti siano superflui, dispendiosi in termini di tempo e leggermente fastidiosi. Se pensi davvero che la persona che viene dietro non riesci a capirlo, allora rifattalo o almeno inseriscilo nel suo metodo con un commento a livello di metodo.

Gli unici commenti che mi piacciono sono quelli che spiegano perché il design attuale è cattivo e come migliorarlo.

Al di fuori di questi commenti "questo è il motivo per cui questo fa schifo", se non riesci a capire cosa fa guardando il codice e leggendo / eseguendo i test, allora non c'è speranza.