Come promuovere il riutilizzo del codice e la documentazione? [chiuso]

Hai bisogno di documentazione, una corretta. Dovrebbe essere facile da trovare e navigare. Hai anche bisogno di disciplina. Se esiste già una soluzione fornita nelle tue librerie di codici riutilizzabili ma lo sviluppatore sceglie di utilizzare la propria soluzione (senza alcuna ragione adeguata), dovresti ripristinare la sua soluzione e dirgli di utilizzare la soluzione esistente.

Sono anche d'accordo con il commento di Euphoric alla domanda. È spesso impossibile riutilizzare qualsiasi cosa tra diversi progetti (in genere tutte le operazioni CRUD hanno lo stesso aspetto, ma di solito non è possibile riutilizzarle).

Accanto ai fattori già menzionati "documentazione", "facile da trovare e navigare", "disciplina" e "codereview"

Il codice resusable deve essere

• facile da usare (= bisogno di esempi, cioè di unittests)
• senza troppe dipendenze per gli altri moduli e
• deve avere una api stabile , quindi non devo aggiornare la mia aplicazione per usare la libreria.

senza gli ultimi due elementi è molto più semplice usare "copia e ereditarietà passata" che non vogliamo.

Penso che il modo migliore per farli effettivamente riutilizzare il codice sia la motivazione. Se metti i componenti riutilizzabili in progetti extra, come suggerito da Euforic, ci metti molto impegno. Dove lavoro, abbiamo realizzato un progetto, che esegue una serie di interfacce predefinite in piani di esecuzione configurabili e fornisce alcuni servizi (ad esempio classi diverse per DB_interaction, un servizio FTP, ...). Il progetto è un grande successo, perché i nostri sviluppatori vogliono utilizzare il micro-framework, perché sta risparmiando loro molto tempo per scrivere codice boilerplate per progetti simili. La stessa cosa vale per le librerie di utilità per elenchi, stringhe, ecc., Ma in questo caso si vorrebbe usare una volta. (perché reinventare il weel?)

Conclusione: i tuoi sviluppatori possono sperimentare i vantaggi di componenti riutilizzabili collaudati. Ma sono anche d'accordo con la risposta di Andrzej Bobak: molte cose non sono riutilizzabili, perché sono simili, ma non uguali.

Questo sarà difficile, perché le persone come scrivono un nuovo codice per componenti semplici e a loro piace farlo il loro modo. È molto più difficile sfruttare una soluzione esistente ed estenderla, piuttosto che scrivere un'implementazione completamente nuova con i nuovi requisiti. Quello che devi fare, come è stato affermato, è avviare un processo di revisione del codice tra il team per aiutare a identificare le situazioni in cui un componente esistente avrebbe dovuto essere usato / esteso al posto di uno nuovo.

Devi anche mantenere una documentazione molto buona e completa in modo che le persone possano farvi riferimento e facilmente trovare ciò di cui hanno bisogno. Se la documentazione è incompleta o non sincronizzata con la realtà, le persone non saranno motivate a cercarla o migliorarla.

Come guida il team, dovresti anche incoraggiare le persone a chiedersi se esiste un componente simile prima di crearne uno e indirizzarlo alla documentazione in modo che possano cercarlo. Certo, il processo di revisione del codice lo catturerà se qualcuno ha perso un componente esistente, ma cosa succede se ha già messo 10 ore di sviluppo nella propria implementazione? Devi evitare queste situazioni imponendo un buon comportamento di ricerca nel team.

Abbiamo affrontato questo problema su un grande progetto al quale sto lavorando attualmente. Negli ultimi mesi abbiamo avuto una certa rotazione di sviluppatori, è anche una base di codice piuttosto ampia e anche quelli che hanno partecipato al progetto fin dall'inizio non ne conoscono ogni centimetro.

Mentre il codice è spesso ben scritto e suddiviso in parti piccole con responsabilità singole e la documentazione è presente, è abbastanza facile perdere qualcosa che è stato fatto. Le convenzioni di denominazione coerenti aiutano molto perché è facile cercare qualcosa in qualsiasi IDE. La documentazione può essere completa, ma man mano che si allunga, è un po 'difficile leggerlo.

Una cosa che abbiamo fatto, a mio parere, ha migliorato notevolmente la situazione è stata l'introduzione di una cosa che chiamiamo Lightning Talks . Ogni volta che qualcuno scrive un pezzo di codice che crede dovrebbe essere noto alla squadra, viene organizzata una breve presentazione (di solito 5-15 minuti). Cerchiamo di farlo una volta alla settimana. I soggetti tendono a variare, dalle nuove caratteristiche e modalità di gestione dei problemi complessi che sono emersi di recente, attraverso approcci di test / codifica, componenti riutilizzabili, discussioni sulle basi della app e refactoring della stessa.

Alcuni argomenti sono menzionati in discorsi simili a livello aziendale. Abbiamo trovato un modo abbastanza efficiente per stimolare la condivisione delle conoscenze. È molto più facile vedere e ricordare una breve presentazione e sapere dove cercare documentazione aggiuntiva o chi rivolgersi per chiedere aiuto piuttosto che partecipare a sessioni di formazione molto lunghe e raramente organizzate o semplicemente sedersi lì, leggendo la copertina dei documenti per coprire.

I colloqui a livello aziendale sono arrivati per primi. Abbiamo appena adottato questo approccio per la condivisione della conoscenza specifica del progetto e penso che funzioni abbastanza bene.

La programmazione accoppiata rende anche la circolazione della conoscenza molto più veloce.

Penso che in realtà si tratti di due domande in una: proverò a rispondere entrambe.

1) Come riduciamo il codice duplicato in un codebase.
Aiuta a ricordare a noi stessi il vantaggio di fare questo: si traduce in un minor numero di bug dovuti alla logica aziendale duplicata e meno codice da mantenere. Il modo migliore per evitare che questo accada è attraverso la comunicazione, come menzionato nelle altre risposte. Sono assolutamente d'accordo con la raccomandazione di utilizzare le revisioni del codice con l'avvertenza in più che è necessario condividere le responsabilità di revisione del codice allo stesso modo per diffondere correttamente le conoscenze. Dovresti inoltre utilizzare gli stand-up giornalieri in modo che gli sviluppatori riconoscano spesso quando qualcuno sta cercando di risolvere un problema per il quale esiste un codice utile esistente. Dovresti anche considerare l'abbinamento del codice in quanto aumenta la condivisione delle conoscenze e aiuta a mantenere disciplinati i programmatori.

Raccomando anche di avvicinare i tuoi sviluppatori il più vicino possibile, preferibilmente nella stessa stanza. Con molte lavagne e spazi condivisi. Poi mandali fuori a mangiare insieme. Più i tuoi sviluppatori si "legano" e meglio si comunicheranno tra loro.

Non sono d'accordo con la raccomandazione di utilizzare un wiki o simile al codice del documento. Indipendentemente dal modo in cui gli sviluppatori disciplinati cercano di essere la documentazione deriverà dal codice originale. Un approccio più efficace sarebbe l'uso della specifica mediante prove di stile di esempio. Questi documentano il codice in un modo che rende chiaro come dovrebbe essere usato e i test falliranno se qualcuno cambia il codice senza cambiare gli esempi.

Hai già una grande base di codice con un sacco di codice duplicato, quindi dovresti probabilmente lavorare per rifattorizzarlo. Può essere difficile trovare codice duplicato che non sia stato tagliato e incollato. Quindi, piuttosto che farlo, ti suggerisco di analizzare la cronologia delle modifiche. Cerca i file che cambiano spesso allo stesso tempo. Ciò probabilmente indicherà problemi di incapsulamento se non indica un codice duplicato effettivo e vale comunque la pena di essere pulito. Se è anche possibile analizzare la cronologia delle correzioni di bug in base alle modifiche al codice, è possibile trovare determinati hotspot in cui sono spesso necessarie correzioni. Analizza questi hotspot e probabilmente scoprirai che molti di questi sono dovuti alla doppia logica di business che uno sviluppatore ha modificato solo in un punto, senza rendersi conto che sarebbe stato necessario cambiarlo due volte.

2) Come dovremmo avvicinarci alla creazione di widget, componenti, librerie, ecc. condivisi che possono poi essere utilizzati in altri progetti .
In questo caso non dovresti cercare di racchiudere la logica aziendale ma condividere un utile codice framework. Questo può essere un difficile equilibrio poiché il costo di creare e mantenere un insieme di componenti condivisi può essere piuttosto ampio e può essere difficile prevedere in quali casi vale la pena farlo. L'approccio che suggerirei qui è una regola dei tre colpi. Non preoccuparti di scrivere due volte una parte di codice simile, ma quando hai bisogno di rifarla una terza volta in un componente condiviso. A questo punto puoi essere ragionevolmente sicuro che sarà utile e hai una buona idea dei requisiti più ampi per il componente. Ovviamente, la comunicazione tra gli sviluppatori è vitale qui.

Considera di rendere possibile la maggior parte del tuo componente condiviso open source. Non è una logica aziendale, quindi non darà molti vantaggi alla tua concorrenza, ma significa che avrai gratuitamente revisori e manutentori extra.

IMMO la chiave non è documentazione o strumenti, la chiave è COMUNICAZIONE. Più di 10 sviluppatori non sono molte persone, alcune cose che migliorano questa comunicazione:

• pair programming: con due persone ci sono più cambiamenti che uno dei due sa che il problema è già stato risolto in un'altra parte del progetto e riutilizzato.

• Proprietà del codice collettivo: tutte le persone lavorano con le diverse parti dei sistemi, in questo modo è molto più facile sapere che qualcosa è già stato fatto in un'altra parte del progetto, per me questa è una pratica fondamentale in un squadra.

• Dare tempo al lavoro di progetti orizzontali: ad esempio, un venerdì o due in un mese, e gli sviluppatori in questo momento possono lavorare nei propri progetti che hanno qualche applicabilità al progetto della tua azienda. In questo modo gli sviluppatori possono scrivere librerie e componenti riutilizzabili, a volte il suo codice è già esistente ma necessita di pulizia e documentazione.

• Realizza talk e workshop: prenota un momento per i talk e gli workshop degli sviluppatori, gli sviluppatori possono parlare delle sue librerie o forse puoi fare workshop di refactoring e prendere del codice duplicato e rimuovere la duplicazione creando un componente riutilizzabile.

Probabilmente la documentazione è necessaria ma è solo una piccola parte della cosa reale di cui hai bisogno: migliora la comunicazione all'interno del tuo team.

Che ne pensi di utilizzare un motore di ricerca locale come Lucene (o qualcosa di più specifico del codice sorgente) per indicizzare il tuo codice? Quando qualcuno inizia a scrivere una nuova classe o una nuova funzione (per esempio), deve provare (come politica interna) un paio di ricerche prima di scrivere il proprio codice. In questo modo puoi evitare troppe comunicazioni e puoi fare affidamento su buoni commenti, metodi e nomi di classi. Mi trovo a farlo con motori di ricerca open source disponibili su internet: non so chi ha scritto cosa o quale sia il nome di un metodo o di una classe, ma con un paio di ricerche o sinonimi trovo sempre ciò di cui ho bisogno.

Hai bisogno di uno strumento che aiuti i tuoi sviluppatori a farlo in modo trasparente. Se i tuoi sviluppatori scoprono quanto tempo possono risparmiare riutilizzando i frammenti di codice (non solo in termini di scrittura del codice, ma ovviamente per garanzia della qualità, integrazione, ecc.), Aiutato da uno strumento efficiente che è facile da usare e direttamente integrati nell'ambiente di sviluppo, ti pregheranno di adottare uno strumento del genere!

Fai attenzione che molte volte la realizzazione di librerie per il riutilizzo del codice non risulti in un enorme vantaggio (tendono a diventare troppo potenti e grandi ...); preferisco invece concentrarmi su snippet semplici, cioè poche righe di codice che risolvono un particolare compito in modo efficace.

In questo modo puoi forzare l'utilizzo di linee guida e best practice fornendo esempi reali che possono essere utilizzati direttamente dai programmatori.

Ci sono diversi strumenti per la gestione degli snippet, consiglio questo: link .

(Disclaimer: sono uno dei fondatori di Snip2Code, e sono stato - insieme ai miei co-fondatori - nella tua stessa mentalità qualche tempo fa: è per questo che abbiamo deciso di iniziare questo progetto, che raccoglie tutti i caratteristiche che ho dichiarato sopra, cioè condivisione di frammenti tra un team, integrazione in IDE come Visual Studio, Eclipse, IntelliJ, Notepad ++, ecc.)