Come introdurre il codice a un collega

Come si fa a introdurre la base di codice, che può essere piuttosto complessa e ingarbugliata con molti "gotchas", a un nuovo membro della tua squadra?

Penso che il modo più semplice sarebbe avere l'architettura generale strutturata con diagrammi e impiegare un paio di settimane (o mesi) dando alla nuova persona compiti ben definiti (e ben definiti) man mano che si abitua al codice.

Tuttavia, in qualità di consulente (e dipendente junior), non posso sempre averlo a causa di vincoli di tempo o designazioni di ruoli di squadra. (Sono stato su questo particolare progetto due volte più di chiunque altro, quindi "junior" non è in alcun modo "meno a conoscenza del codice / progetto".)

Sono stato incaricato parecchie volte di presentare un nuovo membro al progetto e al codice, e purtroppo ogni volta che trovo che non sono molto più bravo di quello precedente. Adoro i diagrammi e le immagini, ma spesso sento che non spiegano adeguatamente la complessità di un sistema. (Che dire di tutti i "gotchas" del piccolo?)

Il progetto sta arrivando al punto in cui lo consegneremo al cliente e, per rendere le cose più difficili, la persona con cui farò un trasferimento di conoscenze è essenzialmente appena uscita dal college. (Non che sto molto meglio quando faccio trasferimenti di conoscenza con sviluppatori senior.)

Frequento un gruppo di utenti una volta al mese e altre opportunità quando si presentano, quindi non sono inutilizzato per essere introdotto a nuovi argomenti, ma sento la mia capacità di replicare una condivisione efficace delle conoscenze dolorosamente inadeguata.

Qualsiasi consiglio sarebbe molto apprezzato. Sto cercando principalmente una linea guida che posso seguire. Ad esempio: da dove inizi? Come procedete? Come si coprono le tecnologie o i modelli non familiari da parte dell'ascoltatore senza passare tutto il giorno? Dove ti leghi tra logica aziendale e struttura del codice?

Grazie!

(Come sempre, non esitare a modificare la domanda come ritieni opportuno.)

Il primo passo è ovviamente quello di rimuovere i "gotchas" dal codice. Il codice chiaro, conciso e coerente è più facile da utilizzare, utilizzare e eseguire il debug.

Da dove inizi?

Chiedo al nuovo arrivato come vogliono entrare nella base di codice. Tutti imparano in modo diverso. Ad alcune persone piace avere piccoli compiti con cui lavorare. Ad alcuni piace eseguire il debug del codice esistente. Alcuni vogliono vedere il codice in esecuzione per capire cosa fa. Alcuni vogliono iniziare dal punto di accesso e navigare. Alcuni vogliono diagrammi visio ... Nessun modello impostato funzionerà meglio per tutti.

Come si coprono le tecnologie o i modelli non familiari da parte dell'ascoltatore senza passare tutto il giorno?

Li evito. Lascia che siano scatole nere fino a quando il nuovo arrivato non le chiede. Quindi fornisci le informazioni sufficienti per ottenere il jist di esso, con il suggerimento che possono imparare di più nel loro tempo libero o chiedere in seguito quando le cose generali sono più conosciute.

Dove ti leghi tra logica aziendale e struttura del codice?

Cerco di non farlo. È quasi sempre meglio per il nuovo arrivato imparare da solo in modo che si trovi nella loro mente in una struttura più naturale per il loro modo di pensare.

Una cosa da ricordare è di mantenere brevi le istruzioni. Le persone tendono a fare il check-out abbastanza rapidamente, quindi ulteriori istruzioni a quel punto non si "attaccano". Mostra loro le cose per 15-60 minuti (persone diverse hanno intervalli di attenzione diversi), quindi prenditi una pausa di 5-30 minuti per elaborarle.

Nella mia esperienza, un buon modo per colmare il divario tra l'ampia panoramica fornita da un diagramma di architettura e i dettagli grintosi di lavorare effettivamente con il codice è fare un drill-down del sistema, cioè cosa succede quando arriva una richiesta (per il codice del server ) o un utente inserisce un input (per il codice client), quindi spiega passo per passo tutti i livelli di codice coinvolti.

Un altro modo è una "visita guidata" del codice sorgente, vale a dire passare attraverso i pacchetti / spazi dei nomi / moduli / directory e spiegare cosa fa il codice in ciascuno di essi in generale. Naturalmente ciò richiede che il codice sia strutturato in modo logico.

Non stai insegnando loro la base di codici, stai insegnando loro il tuo lavoro. Non cercare di pensare a ciò di cui potrebbero aver bisogno, guarda cosa hai effettivamente bisogno di sapere quando fai il tuo lavoro.

Raccogli gli ultimi mesi di cronologia del bug tracker, storie utente di mischia, rapporti sullo stato e commit del controllo del codice sorgente. Quali file hai toccato di più? Quale codice è più problematico? Quali compiti ti hanno impiegato di più? È probabile che, se non l'hai toccato negli ultimi mesi, non è così importante come potresti pensare.

Guarda la pila di stampe sulla tua scrivania. Controlla la cronologia del browser recente. Cerca le e-mail salvate a cui fai spesso riferimento, i contatti che usi, i documenti che hai scaricato. Alcuni dei riferimenti più utili che ho trasmesso ad altri sono le note che ho tenuto per me stesso quando ho appreso o progettato il sistema per la prima volta. Che il materiale di riferimento è più utile a voi ?

Quindi visualizza il tuo backlog noto. Quali cose avresti bisogno di ricercare per completare quei compiti? Quali aree di codice contengono probabilmente il problema? Trasmetti queste informazioni come se stessi prendendo appunti per te stesso.

Se fai riferimento a grafici o diagrammi nel tuo lavoro quotidiano, includili. Se non ti sei mai preso la briga di crearne uno, probabilmente non sarà nemmeno utile per il tuo successore / collega.

Uno dei compiti più difficili durante l'insegnamento è cercare di mettersi nei loro panni. In questo caso, si è nei loro panni. Approfittane.

Il lavoro di supporto è il migliore, prendi un bug facile e guidali attraverso le aree in cui verrà trovato. impareranno rapidamente come il codice si adatta insieme. Naturalmente, verranno a fare domande su questo bug e sulla base di codice, ma ci arriveranno (e riceverai un bug corretto). Spesso è molto più facile capire le cose con esempi, allo stesso modo, è più facile elaborare una base di codice eseguendola in un debugger.

Se non sei sicuro delle modifiche al codice (o lo sono, in genere sarei incerto delle mie correzioni del codice fino a quando non avrò familiarità con la base di codice), puoi esaminarlo prima del check-in.

Naturalmente, le tue idee esistenti su panoramiche generali e diagrammi a blocchi sono i primi passi essenziali.