Come posso trattare con un membro del team che non ama fare commenti nel codice?

Se hai un dipendente che non può seguire le istruzioni, rimproveralo e assicurati che sia chiaro che non aiuterà la sua carriera ad avanzare. La coerenza nello stile di codifica è fondamentale per un team, e se tutti gli altri scrivono commenti e questo non lo è, ciò danneggerà lo stile di codifica.

Detto questo, puoi probabilmente aiutarlo. Nella mia esperienza, quando qualcuno protesta dicendo che impiega troppo tempo c'è una barriera psicologica come ...

1. È consapevole delle sue scelte di codice / design e non vuole esporle in prosa. (Le revisioni del codice possono essere utili per rafforzare la fiducia in se stessi tanto quanto per abbatterle.)
2. Lavora in modo molto lineare e non pensa molto al futuro. Commentare è doloroso perché lo costringe a scaricare il codice immediato che stava per scrivere dalla sua memoria di lavoro per comporre il suo intento in un modo diverso. (Se questo è vero, i commenti diventano molto importanti per la sua qualità del codice.)
3. Storicamente le persone non capiscono i suoi commenti.

Per un programmatore è importante rendersi conto che i commenti sono come test: non sono solo per uso futuro - Sono per il programmatore stesso. Lo costringono a pensare in modo diverso al suo approccio.

Nessuno di questi è un sostituto per CI, test o recensioni di codice. È solo una delle molte parti critiche della codifica che, di per sé, non scrive codice.

Ottieni il software di revisione del codice e usalo bene.

Usiamo il forno e lo adoriamo. Abbiamo una politica che ogni changeset deve essere rivisto (anche se permettiamo agli sviluppatori di approvare / approvare le recensioni su tag e fusioni senza conflitti (anche se molti di noi usano rebaseif), in questo modo possiamo individuare rapidamente i changeset senza recensioni). / p>

Il codice che non è chiaro è il motivo per cui una revisione del codice deve essere rifiutata. Non importa se la correzione è un commento o un codice più chiaro, ma il revisore deve essere in grado di capirlo. Alcuni sviluppatori preferiscono riscrivere il codice, ma altri (me compreso) spesso trovano più semplice esprimere l'intenzione nei commenti (il codice può mostrare facilmente ciò che fa, ma è più difficile mostrare ciò che dovrebbe fare).

Se c'è sempre qualche domanda sulla chiarezza del codice, il revisore vince sempre. Ovviamente l'autore lo capisce, perché lo hanno scritto. Deve essere chiaro a un'altra persona.

Usando un software come Kiln, nessun changeset viene trascurato. Tutti nella mia squadra di sviluppatori lo preferiscono in questo modo. Il software di revisione del codice ha avuto un enorme impatto sulla qualità del nostro codice e sulla qualità dell'applicazione: -)

È facile per gli sviluppatori essere sulla difensiva con recensioni rifiutate quando introducono il software, ma nella mia esperienza, non ci vuole molto tempo per capire che le cose sono migliori in questo modo e abbracciarlo :-)

Modifica: Vale anche la pena notare che cerchiamo di evitare che gli sviluppatori spieghino il codice criptico verbalmente o nei commenti nella recensione. Se qualcosa non è chiaro, il posto migliore per spiegarlo è nel codice (nei commenti o tramite refactoring), quindi aggiungi i nuovi changeset alla stessa recensione.

am I wrong to focus on the code comments or is this indicative of a bigger problem that should be addressed?

Un po '. Il grande codice non ha bisogno di commenti. Comunque, come hai detto, il suo codice non è auto-documentante. Quindi non vorrei concentrarmi sui commenti. Dovresti concentrarti sul miglioramento delle abilità e abilità dei tuoi sviluppatori.

Quindi come farlo? I suggerimenti di Doc Brown sulle sessioni di revisione / refactoring sono una buona idea. Trovo la programmazione della coppia ancora più efficace, ma potrebbe anche essere considerevolmente più difficile da implementare.

È interessante notare che la leggibilità applicata al linguaggio naturale è misurata dalla velocità di lettura e comprensione. Immagino che una regola semplice possa essere effettivamente adottata, se un particolare commento di codice non migliora questa proprietà, può essere evitato .

Perché commenti?

Sebbene il commento al codice sia una forma di documentazione incorporata, ci sono molti modi nei linguaggi di programmazione di fascia alta per evitare la superflua programmazione "eccessivamente documentata" (di codice significativo) usando elementi del linguaggio stesso. È anche una cattiva idea trasformare il codice in elenchi da un libro di testo di programmazione, in cui le singole affermazioni sono letteralmente spiegate in modo quasi tautologico (attenzione all'esempio "/ * incremento di 1 * /" nelle risposte già fornite), rendendo tali commenti pertinenti solo per programmatori inesperti con la lingua.

Ciononostante, è l'intenzione di provare a commentare il codice "poco documentato" (ma privo di significato) che è veramente "la fonte di ogni male". L'esistenza stessa del codice "sotto-documentato" è un cattivo segnale - o è un disordine non strutturato, o un hack bizzarro di mistico scopo perso. Ovviamente, il valore di tale codice è discutibile almeno. Sfortunatamente ci sono sempre degli esempi, quando è davvero meglio introdurre un commento in una sezione di righe di codice (visivamente raggruppate) piuttosto che avvolgerle in una nuova subroutine (attenzione alla "consistenza folle" che "è l'hobgoblin delle piccole menti") .

Leggibilità del codice! = commenti del codice

Il codice leggibile non richiede annotazioni per commenti. In ogni posto particolare nel codice c'è sempre un contesto di un compito che questo particolare codice dovrebbe raggiungere. Se manca lo scopo e / o il codice fa qualcosa di misterioso = evitalo a tutti i costi. Non consentire agli hacker strani di popolare il tuo codice: è un risultato diretto della combinazione di tecnologie buggy con mancanza di tempo / interesse per comprendere le basi. Evita il codice mistico nel tuo progetto!

D'altra parte, Programma leggibile = codice + documentazione può contenere più sezioni legittime di commenti, ad es. per facilitare la generazione della documentazione "commenti su API".

Segui gli standard di stile del codice

È abbastanza divertente che la domanda non riguardi il perché commentare il codice, ma il lavoro di squadra - come produrre codice in stile altamente sincronizzato (che chiunque altro può leggere / comprendere). Stai seguendo gli standard di stile del codice nella tua azienda? Lo scopo principale è evitare di scrivere codice che richiede il refactoring, è troppo "personale" e "soggettivamente" ambiguo. Quindi, immagino, se si vede la necessità di usare lo stile del codice, c'è un serio insieme di strumenti su come implementarlo correttamente - iniziando con l'educazione delle persone e finendo con l'automazione per il controllo di qualità del codice (numerosi lint, ecc.) E (revisione controllo integrato) sistemi di revisione del codice.

Diventa un evangelizzatore della leggibilità del codice

Se accetti che il codice viene letto più spesso di quanto non sia scritto. Se la chiara espressione di idee e pensieri è chiaramente importante per te, indipendentemente dalla lingua utilizzata per comunicare (matematica, codice macchina o vecchio-inglese) .. Se la tua missione è quella di sradicare il modo noioso e brutto del pensiero alternativo .. (scusate , l'ultimo proviene da un altro "manifest") .. porre domande, avviare discussioni, iniziare a diffondere pensieri che provocano libri sulla pulizia del codice (probabilmente non solo qualcosa di simile ai modelli di progettazione di Beck, ma più come già accennato di RC Martin ) che affrontano l'ambiguità nella programmazione. Più avanti un passaggio puntato di idee chiave (citato dal libro di O'Reilly sulla leggibilità)

• Semplifica la denominazione, i commenti e la formattazione con i suggerimenti applicabili ogni riga di codice
• Perfeziona loop, logica e variabili del tuo programma per ridurre complessità e confusione
• Problemi di attacco a livello di funzione, come riorganizzare blocchi di codice per eseguire un'attività alla volta
• Scrivi un codice di test efficace, completo e conciso, oltre che leggibile

Tagliando "commentando", ne rimane ancora uno (suppongo che scrivere codice che non ha bisogno di commenti sia un ottimo esercizio!). La denominazione di identificatori semanticamente significativi è un buon inizio. Quindi, strutturando il codice raggruppando le operazioni logicamente connesse in funzioni e classi. E così via. Un programmatore migliore è uno scrittore migliore (ovviamente, supponendo che vengano fornite altre competenze tecniche).

Prima di tutto, ti suggerirei di ri-indirizzare il tuo approccio sui commenti.

Se si tratta di commenti di documentazione a livello di API (esposti più tardi al pubblico), questo sviluppatore semplicemente non sta facendo il suo lavoro. Ma per tutti gli altri commenti, fai attenzione.

Nella maggior parte dei casi li incontro, i commenti sono malvagi. Consiglierei di leggere il capitolo sui commenti al codice di "Codice pulito" di Robert Martin per capire perché.

I commenti danneggiano il tuo codice in diversi modi:

1) Sono difficili da mantenere. Dovrai fare un lavoro extra durante il refactoring; se cambi la logica descritta nel commento, devi anche modificare il commento.

2) Spesso mentono. Non puoi fidarti dei commenti e devi invece leggere il codice. Il che solleva la domanda: perché avresti bisogno dei commenti?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(L'hash non è la somma ma il prodotto.)

3) I commenti ingombrano il codice e molto raramente aggiungono qualsiasi valore.

La mia soluzione: invece di aggiungere altri commenti, cerca di sbarazzartene affatto!

Questa è in gran parte un'estensione della risposta di tdammers, ma esegue revisioni del codice a intervalli regolari.

Avere lui (e altri sviluppatori) si sieda, cammina attraverso il loro codice e più o meno difendi di fronte ai suoi superiori e i colleghi renderanno tutti migliori programmatori e aggiungeranno valore reale in un periodo di tempo relativamente breve. A breve termine, non fornirà al programmatore alcuna scusa per, al momento della revisione, commentare correttamente il suo codice.

EDIT: Non sono sicuro del motivo per cui qualcuno potrebbe invertire il mio suggerimento - forse ho dato per scontato che i benefici della revisione del codice sarebbero stati conosciuti ... per favore vedi questo thread per un'analisi della comunità della pratica:

La revisione del codice è una buona pratica?

Considerando le opinioni spesso estreme sui commenti, esito a valutare. Detto questo ...

What are some arguments that I can present that if you are going to write (unreadable) code that it should be properly documented?

Capire come scrivere codice manutenibile e leggibile richiede tempo, pratica ed esperienza. I programmatori inesperti (e purtroppo molti esperti) soffrono spesso dell'effetto Ikea ( PDF ) . Questo perché lo hanno costruito e hanno familiarità con esso, e sono sicuri che il codice non sia solo fantastico, ma anche leggibile.

Se la persona è un grande programmatore, allora è richiesta poca o nessuna documentazione. Tuttavia, la maggior parte dei programmatori non è eccezionale e molto del loro codice soffrirà nel reparto "readablity". Chiedere al programmatore mediocre o in via di sviluppo di "spiegare il proprio codice" è utile in quanto li obbliga a vedere il loro codice con un occhio più critico.

Significa "documentare" il loro codice? Non necessariamente. Caso in questione, ho avuto un programmatore simile con questo problema in passato. L'ho costretto a documentare. Sfortunatamente la sua documentazione era indecifrabile come il suo codice, e non aggiungeva nulla. Con le recensioni del codice retrospettivo sarebbe stato più utile.

Tu (o un delegato) dovresti sederti con questo programmatore e prendere un po 'del suo vecchio codice. Non le nuove cose che sa solo lavorando su di esso. Dovresti chiedergli di guidarti attraverso il suo codice con una minima interazione. Questa potrebbe anche essere una sessione separata di "documentazione", in cui spiegherà per iscritto il suo codice. Poi dovrebbe ottenere un feedback su approcci migliori.

Per inciso ... qualche volta è necessaria qualche documentazione indipendentemente da quanto sia buona la "leggibilità" del codice. Le API dovrebbero avere documentazione, operazioni estremamente tecniche e complesse dovrebbero avere una documentazione che aiuti il programmatore a comprendere i processi coinvolti (spesso al di fuori del dominio di conoscenza dei programmatori), e alcune cose come le espressioni regolari complesse dovrebbero documentare realmente ciò con cui si combatte.

Se un membro del team ha difficoltà a comprendere il codice di un altro membro del team (per qualsiasi motivo); allora quel membro della squadra dovrebbe essere in grado di scoprire chi ha scritto il codice originale (qualsiasi sistema di controllo di revisione sensato) e dovrebbe essere incoraggiato a chiedere all'autore del codice di spiegarlo direttamente (ad es. andare alla loro scrivania, sedersi e discuterne).

In questo caso, se la mancanza di commenti è un problema, la persona che non commenta adeguatamente il proprio codice spenderà una grande quantità del proprio tempo per spiegare cosa hanno fatto; e (se sono intelligenti) inizieranno ad aggiungere commenti per evitare di passare il tempo a tutte quelle spiegazioni.

Si noti che incoraggiare i membri del team a chiedersi reciprocamente spiegazioni è utile per altri motivi. Ad esempio, forse un membro del team ha meno esperienza e può imparare cose dai membri del team più esperti.

Per lo più, incoraggiando i membri del team a chiedersi reciprocamente spiegazioni, si crea un sistema di auto-bilanciamento; dove diversi membri del team si "auto-regolano" l'un l'altro.

Molti progetti richiedono la documentazione del codice: documento di interfaccia, documento di progettazione, ...

Alcuni progetti richiedono che tale documentazione sia inserita nei commenti del codice ed estratta con strumenti come Doxygen o Sphinx o Javadoc, in modo che codice e documentazione siano più coerenti.

In questo modo, gli sviluppatori sono tenuti a scrivere commenti utili nel codice e questo compito è integrato nella pianificazione del progetto.

Indicherò a cosa suggeriscono la maggior parte delle risposte e dei commenti: probabilmente devi capire il vero problema qui piuttosto che cercare di spingere la tua soluzione percepita attraverso.

Sei motivato a vedere commenti nel suo codice; perché ? Hai dato una ragione; perché è questa ragione così importante per te? È più motivato a fare qualcos'altro, invece; perché ? Darà una ragione; perché è questa ragione così importante per lui? Ripeti questo fino ad arrivare al livello in cui il conflitto sorge veramente, e prova a trovare una soluzione con cui entrambi puoi convivere. Scommetto che ha ben poco a che fare con i commenti.

Se segui un buon standard di codifica, sarà richiesto un numero minimo di commenti. le convenzioni di denominazione sono importanti. I nomi dei metodi e i nomi delle variabili dovrebbero descrivere il loro ruolo ..

Il mio TL mi suggerisce di usare meno commenti. vuole che il mio codice sia comprensibile e auto descrittivo.  semplice esempio: nome variabile per il tipo di stringa utilizzato per il modello di ricerca

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Adoro le risposte alla revisione del codice, ma forse anche il mio processo sarà di aiuto.

Adoro i commenti, ma non li inserisco quasi mai nel codice al primo passaggio. Forse è solo il mio stile, ma colpirò la stessa sezione di codice da 3 a 5 volte durante lo sviluppo (refactoring, scrittura di test, ecc.)

Ogni volta che mi sento un po 'confuso o quando qualcuno mi fa una domanda su una sezione di codice, cerco di risolverlo in modo che abbia senso.

Questo può essere semplice come aggiungere un commento rimuovendo un insieme di operazioni confuse nella propria funzione o può innescare un refact più grande come l'estrazione di un nuovo oggetto.

Ti suggerisco di incoraggiare tutti nel gruppo a "riconoscere" che il loro codice sia leggibile per gli altri - questo significa che ogni volta che qualcuno ti fa una domanda sul tuo codice, ti impegni a fare una modifica - o meglio ancora abbinalo con quella persona per fare il resto giusto allora!

Considera seriamente di spingere per questo come parte del tuo "contratto di squadra" (e creare definitivamente un contratto se non ne hai uno) - in questo modo tutti sono d'accordo su di esso e lo hai messo su un muro da qualche parte in modo che non c'è alcuna domanda su ciò che hai accettato di fare.

Forse a questo ragazzo deve essere dato un apprezzamento per una buona disciplina di codifica e perché è importante che altre persone capiscano il codice che ha scritto.

Ho lavorato su codebase veramente terribili nella mia carriera, in cui il codice era organizzato in modo così scadente, i nomi delle variabili erano così poveri, i commenti così cattivi o inesistenti, che il codebase ha danneggiato la mia produttività. Non puoi lavorare per correggere o migliorare una base di codice che non capisci, e se è scritta in modo impenetrabile ai nuovi arrivati, passeranno più tempo a cercare di capirlo piuttosto che a lavorarci su.

Non c'è insegnante migliore di una dura esperienza!

Ogni base di codice ha alcuni bit orribili in agguato, parti del sistema che nessuno vuole toccare perché hanno paura di rompere qualcosa, o non possono fare alcun lavoro significativo perché chi ha scritto il codice è a lungo abbandonato e preso la loro comprensione del codice con loro. Se quel codice non è commentato e non è auto-documentante, peggiora solo le cose.

Ti suggerisco di trovare il bit della tua base di codice così e di affidare la tua problematica responsabilità al programmatore. Dagli la proprietà, fallo carico di responsabilità, lascia che impari la vera pena di lavorare su un codice che non può essere mantenuto perché non è ben documentato o impossibile da capire in un breve lasso di tempo. Dopo alcuni mesi di lavoro, sono sicuro che inizierà a venire in giro.

Dagli qualche altro codice senza commenti e chiedigli di capire il codice. Può essere che capisca l'importanza dei commenti appropriati allora.

Questo programmatore esegue una manutenzione del codice. In caso contrario, dovrebbe: verificare la presenza di qualsiasi progetto non gradito e assegnargli la manutenzione.

Di solito questi sono i progetti mal documentati in cui perdi ore cercando di capire cosa sta succedendo per correggere ciò che avrebbe potuto essere facile da correggere. Se questo tipo di esperienza non lo rende aggiornato, la documentazione corretta e utile non lo farà.

In uno dei miei progetti passati mancavano dozzine di commenti (algoritmo, risultati o qualche JavaDoc di base), quindi ho deciso di creare 130 problemi per lui, notifica via e-mail su ogni problema ogni 4 giorni. Dopo 3 settimane ha avuto 280 problemi, poi ha deciso di scrivere commenti.

I commenti hanno uno scopo e un solo scopo:

Perché questo codice fa questa cosa?

Se un commento non spiega perché qualcosa è così com'è, allora dovrebbe essere rimosso. I commenti inutili che ingombrano il codice sono meno che inutili, sono attivamente dannosi.

Ho l'abitudine di rendere i miei commenti la cosa più ovvia del mio IDE. Sono evidenziati con testo bianco su sfondo verde. Attira davvero la tua attenzione.

Questo perché il codice spiega cosa sta facendo e i commenti sono per perché lo sta facendo. Non posso sottolinearlo abbastanza.

Un buon esempio di commento:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Un cattivo esempio:

/* instantiate clsUser */

Se stai usando commenti come "sezioni" di codice: taglia il tuo metodo mastodontico in funzioni nominative più piccole e utili e rimuovi i commenti.

Se stai dicendo cosa stai facendo nella riga successiva: rendi il codice auto-esplicativo e rimuovi il commento.

Se stai usando commenti come messaggi di avviso: assicurati di dire perché.

Per integrare le risposte qui, potrei aggiungere "Se vuoi farlo bene, devi farlo da solo."

Non intendo diventare "chief code commenter", intendo diventare un modello di ruolo nel dimostrare ciò che vorresti fare a questo altro sviluppatore. Dicono che mostrare è più efficace di che dice . Se puoi dimostrare il beneficio di commenti di qualità, o persino di mentore di questo altro sviluppatore (nella misura in cui è disposto a farlo), potresti trovare più successo nell'adozione dei commenti di codice.

Allo stesso modo, a casa ci sono alcune faccende domestiche che non mi interessa fare. Tuttavia, quelle stesse faccende sono le faccende domestiche di mia moglie ... faccende che devono essere fatte per essere felice. La stessa situazione si applica viceversa. Penso che potresti dover accettare che questo altro sviluppatore abbia priorità diverse da te, e non sarà d'accordo con te su tutto. La soluzione che io e mia moglie abbiamo trovato è che per quelle faccende domestiche dobbiamo semplicemente farlo da soli, anche se questo significa fare un po 'più di lavoro da soli.

Semplice: se il dipendente non fa commenti, digli di premere shift+alt+j per il commento automatico in ogni metodo contemporaneamente inserendo il codice. per favore fai una revisione del codice per evitare questi problemi.