Come posso suggerire con tatto miglioramenti al codice mal progettato di altri durante la revisione?

Sono un grande sostenitore del codice pulito e dell'artigianato del codice, anche se attualmente sto svolgendo un lavoro in cui questo non è considerato una priorità assoluta. A volte mi trovo in una situazione in cui il codice di un peer è pieno di design disordinato e pochissima preoccupazione per la manutenzione futura, sebbene sia funzionale e contenga poco o nessun bug.

Come si fa a suggerire miglioramenti in una revisione del codice quando si ritiene che ci sia così tanto da cambiare e che ci sia una scadenza in arrivo? Tieni presente che suggerire che i miglioramenti verranno apportati dopo la scadenza potrebbe significare che saranno completamente declassati in base all'arrivo di nuove funzionalità e correzioni di bug.

1. Ricontrolla la tua motivazione. Se ritieni che il codice debba essere modificato, dovresti essere in grado di articolare alcuni motivi per cui pensi che debba essere modificato. E quella ragione dovrebbe essere più concreta di "Avrei fatto diversamente" o "è brutta". Se non riesci a indicare un vantaggio derivante dalla modifica proposta, non ha molto senso dedicare tempo (ovvero denaro) a cambiarla.

2. Ogni riga di codice nel progetto è una riga che deve essere mantenuta. Il codice dovrebbe essere lungo quanto deve essere necessario per svolgere il lavoro, essere facilmente comprensibile e non più. Se riesci ad abbreviare il codice senza sacrificare la chiarezza, va bene. Se riesci a farlo aumentando la chiarezza, è molto meglio.

3. Il codice è come concreto: è più difficile cambiare dopo essere stato seduto per un po '. Se possibile, suggerisci le modifiche in anticipo, in modo da ridurre al minimo i costi e il rischio delle modifiche.

4. Ogni modifica costa denaro. Riscrivere il codice che funziona e che è improbabile che debba essere modificato potrebbe essere uno sforzo sprecato. Focalizza la tua attenzione sulle sezioni che sono più soggette a modifiche o che sono più importanti per il progetto.

5. La forma segue la funzione e talvolta viceversa. Se il codice è disordinato, è più probabile che contenga anche bug. Cerca questi bug e critica la funzionalità imperfetta piuttosto che il fascino estetico del codice. Suggerire miglioramenti che rendono il codice lavorare meglio e rendere il funzionamento del codice più facile da verificare.

6. Distinguere tra design e implementazione. Una classe importante con un'interfaccia scadente può diffondersi attraverso un progetto come il cancro. Non solo diminuirà la qualità del resto del progetto, ma aumenterà anche la difficoltà di riparare il danno. D'altra parte, una classe con un'interfaccia ben progettata ma un'implementazione scadente non dovrebbe essere un grosso problema. È sempre possibile implementare nuovamente la classe per prestazioni o affidabilità migliori. Oppure, se funziona correttamente ed è abbastanza veloce, puoi lasciarlo solo e sentirti sicuro nella consapevolezza che la sua rotta è ben incapsulata.

Per riassumere tutti i punti sopra: Assicurati che le modifiche proposte aggiungano valore.

C'è un punto debole per aggiungere valore attraverso il refactoring. I cambiamenti devono realizzare tre cose:

• migliorare il codice che potrebbe cambiare
• aumentare la chiarezza
• costa meno sforzo

considerazioni:

1. Sappiamo che il codice pulito è meno costoso da scrivere e mantenere ed è più divertente su cui lavorare. Il tuo compito è vendere quell'idea alle persone della tua azienda. Pensa come un venditore, non come un brontolone arrogante (cioè non come me).
2. Non puoi vincere, puoi solo perdere di meno.
3. Concentrati sull'aggiunta di valore reale, non solo sulla bellezza. Mi piace che il mio codice abbia un bell'aspetto, ma a volte devo accettare di più le cose economiche.
4. Un buon modo per trovare il punto debole è seguire il Principio Boy Scout: quando lavori su un'area di codice, lascialo sempre in forma migliore di quello che hai trovato.
5. Un piccolo miglioramento è meglio di nessun miglioramento.
6. Fare buon uso di strumenti automatizzati. Ad esempio, gli strumenti che appena ripulire un po 'di formattazione può fare un mondo di differenza.
7. Vendi altre idee che incidentalmente migliorano la chiarezza del codice. Ad esempio, i test unitari incoraggiano la decomposizione di metodi grandi in metodi più piccoli.

Se il codice funziona senza gravi bug e una scadenza importante (come in effetti P&L o PR aziendale) è imminente, è troppo tardi per suggerire miglioramenti che richiedono grandi cambiamenti. Anche miglioramenti al codice possono creare rischi per la distribuzione del progetto. Il tempo per i miglioramenti era precedente nel progetto, quando c'era più tempo per investire nella solidità futura della base di codice.

La revisione del codice ha 3 scopi:

1. Verifica di bug

2. Verifica per vedere dove potrebbe essere migliorato il codice

3. Strumento didattico per chiunque abbia scritto il codice.

La valutazione della qualità di progettazione / codice riguarda ovviamente il n. 2 e il n. 3.

Per quanto riguarda il n. 2:

• Rendi MOLTO chiaro quali sono i vantaggi delle modifiche proposte rispetto ai costi da correggere. Come ogni decisione commerciale, questo dovrebbe riguardare l'analisi costi / benefici.

  Ad esempio "L'approccio X alla progettazione ridurrebbe in modo significativo la probabilità che si verifichi il bug Y quando si esegue la modifica Z e sappiamo che questo pezzo di codice subisce modifiche di tipo Z ogni 2 settimane. Il costo di gestione dell'interruzione della produzione dal bug Y + trova il bug + correzione e rilascio della correzione + costo opportunità non derivante dalla consegna della prossima serie di imprese è $A; mentre il costo di ripulire il codice ora e il costo opportunità (ad esempio il prezzo di spedizione in ritardo o con meno funzionalità) è $B. Ora, valutare - o piuttosto avere il vostro team leader / manager - valutare $Avs $Be decidere.

  • Ciò aiuterà il team intelligente a condurre in modo efficace questo. Ad esempio, prenderanno una decisione razionale usando le informazioni FULL

  • Questo (specialmente se lo pronunci bene) aumenterà il TUO status - ad esempio, sei abbastanza intelligente da vedere i vantaggi di un design migliore, E abbastanza intelligente da non esigerlo religiosamente senza ponderare le considerazioni aziendali.

  • E, nel probabile caso in cui si verifica il bug Z, ottieni ancora più leva sul prossimo set di suggerimenti.

Per quanto riguarda il n. 3:

• Delineare MOLTO chiaramente "deve correggere" bug / problemi da "Questa è una buona pratica e dovrebbe davvero essere risolta SE possiamo risparmiare risorse - vedi analisi pro / contro allegate" miglioramenti del design (allegare le cose descritte per il n. 2 sopra) vs " Queste sono linee guida generali che ritengo possano aiutarti a migliorare la robustezza del tuo codice in modo da poter mantenere più facilmente il codice "modifiche opzionali. Si prega di notare la formulazione - non si tratta di "rendere il codice simile a quello che voglio" - è "se lo fai, otterrai vantaggi a, b, c". Il tono e l'approccio sono importanti.

Scegli le tue battaglie, se sta per scadere una scadenza, non fare nulla. La prossima volta che qualcun altro sta rivedendo o gestendo il codice e continuano ad avere problemi con esso, allora avvicinati a loro con l'idea che come team dovresti essere più concentrato sulla qualità del codice quando rivedi il codice in modo da non avere così tanti problemi in seguito.

Dovrebbero vedere il valore prima di fare il lavoro extra.

Inizio sempre il mio commento con "Vorrei", il che indica che il mio è semplicemente uno dei tanti punti di vista.

Includo anche sempre un motivo.

" Vorrei estrarre questo blocco in un metodo a causa della leggibilità."

Commento tutto; grande e piccolo. A volte faccio più di un centinaio di commenti su una modifica, nel qual caso consiglio anche la programmazione in coppia e mi offro come ala.

Sto cercando di stabilire un linguaggio comune per motivi; leggibilità, DRY, SRP, ecc.

Ho anche creato una presentazione su Clean Code e Refactoring spiegando perché e mostrando come, che ho tenuto ai miei colleghi. L'ho tenuto tre volte finora, e una consulenza che stiamo usando mi ha chiesto di trattenerlo di nuovo per loro.

Ma alcune persone non ascolteranno comunque. Poi mi rimane il grado di tiratura. Sono il capo del design. La qualità del codice è mia responsabilità. Questo cambiamento non passerà sul mio orologio nel suo stato attuale.

Si prega di notare che sono più che disposto a rinunciare a qualsiasi commento che faccio; per motivi tecnici, scadenze, prototipi, ecc. Ho ancora molto da imparare anche sulla programmazione e ascolterò sempre la ragione.

Oh, e recentemente mi sono offerto di comprare il pranzo per il primo della mia squadra che ha presentato una modifica non banale su cui non ho avuto alcun commento. (Ehi, devi divertirti anche tu. :-)

A volte mi trovo in una situazione in cui il codice di un peer è pieno di design disordinato e pochissima preoccupazione per la manutenzione futura, sebbene sia funzionale e contenga poco o nessun bug.

Questo codice è terminato. A un certo punto, le riprogettazioni diventano troppo costose per giustificare. Se il codice è già funzionante con pochi o nessun bug, allora sarà una vendita impossibile. Suggerisci alcuni modi per ripulirlo in futuro e andare avanti. Se / quando il codice si romperà in futuro, rivalutare il valore di una riprogettazione quindi. Potrebbe non rompersi mai, il che sarebbe fantastico. Ad ogni modo, sei nel punto in cui ha senso scommettere che non si romperà, dal momento che il costo sarà lo stesso ora o più tardi: redesign, terribile riprogettazione.

Quello che devi fare in futuro è avere iterazioni di sviluppo più strette. Se fosse stato in grado di rivedere questo codice prima che fosse stato investito tutto il lavoro di risoluzione dei bug, avrebbe avuto senso suggerire una riprogettazione. Verso la fine, non ha mai senso eseguire importanti refactoring a meno che il codice non sia scritto in un modo sostanzialmente non sostenibile e si sappia con certezza che il codice dovrà essere cambiato subito dopo il rilascio.

Data la scelta tra le due opzioni (refactor o no refactor), pensa a quale suono sembra vendere più intelligente:

Ehi capo, eravamo nei tempi previsti e tutto funzionava, ma ora ricostruiremo un sacco di cose in modo da poter aggiungere la funzione X in futuro.

o

Ehi capo, siamo pronti per il rilascio. Se dovessimo mai aggiungere la funzione X, potrebbero volerci un paio di giorni in più.

Se hai detto uno dei due, il tuo capo probabilmente direbbe:

Chi ha detto qualcosa sulla caratteristica X?

La linea di fondo è che a volte un po 'di debito tecnico ha senso, se non si fosse in grado di correggere alcuni difetti quando era economico (iterazioni iniziali). La progettazione di codici di qualità ha rendimenti decrescenti man mano che ti avvicini a una funzionalità completata e alla scadenza.

[Questa risposta è un po 'più ampia della domanda originariamente posta, poiché questo è il reindirizzamento per tante altre domande sulle revisioni del codice.]

Ecco alcuni principi che trovo utili:

Criticare privatamente, lodare pubblicamente. Fai sapere a qualcuno di un bug nel suo codice uno contro uno. Se hanno fatto qualcosa di geniale o hanno assunto un compito che nessuno voleva, lodateli in una riunione di gruppo o in un'email inviata al team.

Condividi i tuoi errori. Condivido la storia della mia disastrosa prima recensione di codice (ricevuta) con studenti e colleghi junior. Ho anche fatto sapere agli studenti che ho catturato il loro bug così rapidamente perché l'ho fatto prima di me stesso. In una revisione del codice, questo potrebbe venire fuori come: "Penso che tu abbia sbagliato le variabili dell'indice qui. Controllo sempre che a causa del tempo ho sbagliato i miei indici e fatto cadere un data center." [Sì, questa è una storia vera.]

Ricorda di fare commenti positivi. Un breve "bello!" o "trucco pulito!" può rendere il giorno di un programmatore junior o insicuro.

Supponiamo che l'altra persona sia intelligente ma a volte disinteressata. Non dire: "Come ti aspetti che il chiamante ottenga il valore restituito se non lo restituisci effettivamente ?!" Dì: "Sembra che tu abbia dimenticato la dichiarazione di ritorno". Ricorda che hai scritto un codice orribile ai primi tempi. Come qualcuno ha detto una volta, "Se non ti vergogni del tuo codice di un anno fa, non stai imparando".

Salva il sarcasmo / il ridicolo per gli amici che non sono sul posto di lavoro. Se il codice è terribilmente terribile, scherzalo altrove. (Trovo conveniente essere sposato con un collega programmatore.) Ad esempio, non condividerei i seguenti cartoni (o questo ) con i miei colleghi.

Quando un cucchiaio di zucchero aiuta a ridurre la medicina, e ciò che è sbagliato può essere espresso in modo succinto - non ci sono 20 cose sbagliate - Condurrò con una forma che suggerisce che non ho alcun interesse, nessun ego investito in ciò che voglio essere ascoltato. Di solito è qualcosa del tipo:

Mi chiedo se sarebbe meglio ...

o

Ha senso ...

Se i motivi sono abbastanza ovvi, non li dichiaro. Ciò dà ad altre persone la possibilità di assumere un po 'di proprietà intellettuale del suggerimento, come in:

"Sì, è una buona idea, perché <la tua ovvia ragione qui >."

Se il miglioramento è abbastanza ovvio, ma non tanto da farmi sembrare un idiota per non pensarci, e il motivo per farlo riflette un valore condiviso con l'ascoltatore, allora a volte non lo suggerisco nemmeno, invece:

Mi chiedo se c'è un modo per ... <dichiarazione di valore condiviso qui>

Questo è solo per trattare con persone molto sensibili - con la maggior parte dei miei coetanei, glielo lascio!

Le revisioni del codice non sono sempre finalizzate a migliorare.

Una recensione verso la fine di un progetto, come sembra essere il caso qui, è solo così che tutti sanno da dove cominciare a cercare quando arrivano i bug (o per un progetto meglio progettato quali potrebbero essere disponibili per un successivo riutilizzo). Qualunque sia il risultato della recensione, semplicemente non c'è tempo per cambiare nulla.

Per apportare effettivamente modifiche è necessario discutere il codice e progettare molto prima nel progetto: il codice è molto più facile da modificare quando esiste solo quando si parla di possibili approcci.

La tua domanda è "Come revisionare il codice progettato male?":

La risposta IMO è semplice. Parla del DESIGN del codice e di come il design è difettoso o non soddisfa i requisiti. Se si sottolinea un design errato o "non soddisfa i requisiti", lo sviluppatore sarà costretto a modificare il proprio codice perché non fa ciò che deve fare.

Se il codice è "funzionalmente sufficiente" e / o "soddisfa le specifiche" e / o "soddisfa i requisiti":

Se sei un pari di questo sviluppatore, non hai alcun potere diretto che ti consenta di "dirgli" di apportare modifiche.

Vi sono ancora un paio di opzioni:

1. Devi usare la tua "influenza" personale (una forma di "potere" che è indiretto) e / o la tua capacità di essere "persuasivo"
2. partecipare al gruppo di "elaborazione del codice" della propria organizzazione e iniziare a fare della "manutenzione del codice" una priorità più elevata.
3. Morde il proiettile e impara a leggere il codice schifoso più velocemente / più fluentemente in modo da non essere bloccato (sembra che continui ad essere bloccato o rallentato quando incontri codice schifoso) su codice schifoso.
   • Questo ti renderà anche un programmatore più forte.
   • E ti permetterà di correggere il codice schifoso quando stai lavorando sul codice schifoso.
   • E questo ti consentirà anche di lavorare su più progetti perché molti progetti hanno un codice schifoso che è funzionale ... ma un sacco di codice schifoso.
4. Dare l'esempio. Rendi il tuo codice migliore ... ma non cercare di essere un perfezionista.
   • Perché allora diventerai "il ragazzo lento che non riesce a rispettare le scadenze, critica sempre e pensa di essere migliore di tutti gli altri".

Trovo che non ci siano proiettili d'argento. Devi usare tutti e tre e devi essere creativo nell'uso di tutti e tre.

In caso di design paralizzante, il tuo obiettivo dovrebbe essere quello di massimizzare l' incapsulamento . In questo modo, diventa più facile sostituire le singole classi / file / subroutine con classi meglio progettate.

Concentrarsi sul garantire che le interfacce pubbliche dei componenti siano ben progettate e che i meccanismi interni siano accuratamente nascosti. Inoltre, i wrapper di archiviazione dei dati sono essenziali. (Può essere molto difficile modificare grandi quantità di dati memorizzati, quindi se si ottiene "bleeding dell'implementazione" in altre aree del sistema, ci si trova in difficoltà).

Dopo aver rimosso le barriere tra i componenti, concentrati sui componenti che hanno maggiori probabilità di causare problemi importanti.

Ripetere fino alla scadenza o fino a quando il sistema non è "perfetto".

Invece di criticare direttamente il codice di qualcuno, è sempre meglio essere costruttivi nei nostri commenti durante la revisione del codice.

Un modo che seguo è

1. sarà ottimale se lo facciamo in questo modo.
2. Scriverlo in questo modo lo farà correre più veloce.
3. Il tuo codice sarà molto più leggibile se fai "questo" "questo" e "questo"

Tali commenti saranno presi sul serio anche se le tue scadenze stanno arrivando. E probabilmente sarà implementato nel prossimo ciclo di sviluppo.

La revisione del codice deve essere integrata con la cultura e il ciclo di sviluppo per funzionare. Non è probabile che la pianificazione di una revisione del codice di grandi dimensioni alla fine dello sviluppo della funzione X funzionerà. Prima di tutto, apportare le modifiche sarà più difficile e qualcuno probabilmente si sentirà in imbarazzo - creando resistenza all'attività.

È necessario disporre di commit precoci e frequenti, associati a revisioni a livello di commit. Con gli strumenti di analisi del codice in atto, la maggior parte delle recensioni sarà rapida. Strumenti di analisi / revisione del codice automatizzati come FindBugs e PMD ti aiuteranno a ottenere una grande classe di errori di progettazione fuori dalla porta. Tuttavia, non ti aiuteranno a risolvere i problemi a livello di architettura, quindi è necessario disporre di un progetto solido in atto e giudicare il sistema complessivo rispetto a tale progetto.

Aumenta la qualità delle revisioni del codice.

Oltre alla qualità del codice in esame, esiste una qualità della revisione del codice stesso:

• Le modifiche proposte sono davvero un miglioramento rispetto a quanto è presente?
• O solo una questione di opinione?
• A meno che qualcosa di molto ovvio, il recensore abbia spiegato correttamente, perché ?
• Quanto ci è voluto? (Ho visto recensioni che durano mesi, con lo sviluppatore sotto revisione incaricato di risolvere tutti i numerosi conflitti di unione).
• Tono?

È molto più facile accettare una revisione del codice di buona qualità rispetto ad alcuni toelettatura dell'ego per lo più discutibili.

Ci sono due questioni importanti nella domanda, la parte delicatamente e la scadenza che si avvicina . Queste sono questioni distinte: la prima è una questione di comunicazione e dinamiche di gruppo, la seconda è una questione di pianificazione e definizione delle priorità.

Tatticamente . Presumo che tu voglia evitare ego spazzolato e respingere negativamente le recensioni. Alcuni suggerimenti:

• Avere una comprensione condivisa su standard di codifica e principi di progettazione.
• Non criticare o rivedere mai lo sviluppatore , solo il codice . Evita la parola "tu" o "il tuo codice", parla solo del codice in esame, staccato da qualsiasi sviluppatore.
• Metti il ​​tuo orgoglio nella qualità del codice completo , in modo tale che i commenti di revisione che aiutano a migliorare il risultato finale siano apprezzati.
• Suggerisci miglioramenti piuttosto che domanda. Avere sempre un dialogo se non sei d'accordo. Cerca di capire l'altro punto di vista quando non sei d'accordo.
• Le recensioni vanno in entrambi i modi. Vale a dire che la persona che hai esaminato riveda il tuo codice successivamente. Non hai recensioni "a senso unico".

La seconda parte è la definizione delle priorità . Hai molti suggerimenti per miglioramenti, ma poiché la scadenza si avvicina, c'è solo il tempo per applicarne alcuni.

Bene, prima vuoi evitare che ciò accada in primo luogo! Puoi farlo eseguendo revisioni continue e incrementali. Non lasciare che uno sviluppatore lavori per settimane su una funzione e quindi rivedi tutto all'ultimo momento. In secondo luogo, le revisioni del codice e il tempo di attuazione dei suggerimenti di revisione dovrebbero far parte della pianificazione e delle stime regolari per qualsiasi attività. Se non c'è abbastanza tempo per rivedere correttamente, qualcosa è andato storto nella pianificazione.

Ma supponiamo che qualcosa sia andato storto nel processo e ora ti trovi di fronte a una serie di commenti di revisione e non hai il tempo di implementarli tutti. Devi dare la priorità. Quindi vai per le modifiche che saranno più difficili e più rischiose da cambiare in seguito se lo rimandi.

La denominazione degli identificativi nel codice sorgente è incredibilmente importante per la leggibilità e la manutenibilità, ma è anche abbastanza facile e a basso rischio cambiare in futuro. Lo stesso vale per la formattazione del codice. Quindi non concentrarti su quella roba. D'altra parte, la sanità mentale delle interfacce esposte pubblicamente dovrebbe avere la massima priorità, dal momento che sono davvero difficili da cambiare in futuro. È difficile modificare i dati persistenti: se si inizia a memorizzare dati incoerenti o incompleti in un database, in futuro è davvero difficile da correggere.

Le aree coperte da unit test sono a basso rischio. Puoi sempre risolverli in seguito. Le aree che non lo sono, ma che potrebbero essere testate in unità hanno un rischio inferiore rispetto alle aree che non possono essere testate in unità.

Supponi di avere un grosso pezzo di codice senza test unitari e tutti i tipi di problemi di qualità del codice, inclusa una dipendenza hardcoded da un servizio esterno. Iniettando invece questa dipendenza, si rende testabile il blocco di codice. Ciò significa che in futuro è possibile aggiungere test e quindi lavorare per risolvere il resto dei problemi. Con la dipendenza hardcoded non è nemmeno possibile aggiungere test. Quindi scegli prima questa correzione.

Ma per favore cerca di evitare di finire in questo scenario in primo luogo!