Bagaimana cara mengenalkan kode kepada seorang kolega

Bagaimana Anda bisa memperkenalkan basis kode, yang mungkin agak rumit dan kusut dengan banyak "gotchas," kepada anggota baru tim Anda?

Saya pikir cara termudah adalah dengan membuat arsitektur keseluruhan ditata dengan diagram, dan mengambil beberapa minggu (atau bulan) memberikan orang baru tugas yang didefinisikan dengan baik (dan cakupannya baik) karena ia menjadi lebih terbiasa dengan kode.

Namun, sebagai konsultan (dan karyawan junior, pada saat itu), saya tidak dapat selalu memiliki itu karena keterbatasan waktu atau penunjukan peran tim. (Saya telah mengerjakan proyek khusus ini dua kali lebih lama dari yang lain, jadi "junior" sama sekali tidak "kurang tahu tentang kode / proyek.")

Saya telah ditugaskan beberapa kali sekarang untuk memperkenalkan anggota baru ke proyek dan kode, dan sayangnya setiap kali saya menemukan saya tidak jauh lebih baik daripada yang sebelumnya. Saya suka diagram dan gambar, tetapi sering merasa bahwa mereka tidak cukup memperhitungkan kompleksitas dalam suatu sistem. (Bagaimana dengan semua "gotchas" kecil?)

Proyek ini sampai pada titik di mana kami akan memberikannya kepada klien, dan untuk membuat hal-hal lebih menantang, orang yang saya akan lakukan transfer pengetahuan dengan dasarnya hanya keluar dari perguruan tinggi. (Bukannya aku jauh lebih baik ketika melakukan transfer pengetahuan dengan pengembang senior.)

Saya menghadiri grup pengguna sebulan sekali dan peluang lain ketika mereka muncul, jadi saya tidak terbiasa diperkenalkan dengan topik baru, tetapi merasakan kemampuan saya untuk mereplikasi berbagi pengetahuan yang efektif sangat tidak memadai.

Saran apa pun akan sangat dihargai. Saya mencari pedoman yang bisa saya ikuti. Misalnya: Di mana Anda mulai? Bagaimana Anda melanjutkan? Bagaimana Anda membahas teknologi atau pola asing pada bagian pendengar tanpa menghabiskan waktu seharian? Di mana Anda mengikat logika bisnis vs struktur kode?

Terima kasih!

(Seperti biasa, silakan mengedit pertanyaan sesuai keinginan Anda.)

Langkah pertama tentu saja untuk menghapus "gotcha" dari kode. Kode yang jelas, ringkas, konsisten lebih mudah untuk masuk, bekerja dengan, dan men-debug.

Di mana Anda mulai?

Saya bertanya kepada pendatang baru bagaimana mereka ingin masuk ke basis kode. Setiap orang belajar secara berbeda. Beberapa orang suka memiliki tugas kecil untuk dikerjakan. Beberapa suka men-debug kode yang ada. Beberapa ingin melihat kode berjalan untuk memahami apa fungsinya. Beberapa ingin memulai di titik masuk dan hanya berkeliling. Beberapa orang menginginkan diagram visio ... Tidak ada pola pengaturan yang akan bekerja paling baik untuk semua orang.

Bagaimana Anda membahas teknologi atau pola asing pada bagian pendengar tanpa menghabiskan waktu seharian?

Saya menghindarinya. Biarkan mereka menjadi kotak hitam sampai pendatang baru bertanya tentang mereka. Kemudian berikan informasi yang cukup untuk mendapatkan intisari, dengan petunjuk bahwa mereka dapat belajar lebih banyak pada waktu mereka sendiri, atau bertanya kemudian kapan hal-hal umum lebih dikenal.

Di mana Anda mengikat logika bisnis vs struktur kode?

Saya mencoba untuk tidak. Hampir selalu lebih baik bagi pendatang baru untuk belajar sendiri sehingga ia berada dalam pikiran mereka dalam struktur yang lebih alami dengan cara berpikir mereka.

Satu hal yang perlu diingat adalah untuk menjaga instruksi singkat. Orang-orang cenderung memeriksa dengan cepat, jadi instruksi apa pun pada saat itu tidak 'melekat'. Tunjukkan pada mereka hal-hal selama 15-60 menit (orang yang berbeda memiliki rentang perhatian yang berbeda) kemudian istirahat 5-30 menit bagi mereka untuk memprosesnya.

Dalam pengalaman saya, cara yang baik untuk menjembatani kesenjangan antara gambaran umum luas yang diberikan diagram arsitektur dan rincian sebenarnya dari bekerja dengan kode adalah dengan melakukan drill-down dari sistem, yaitu apa yang terjadi ketika permintaan datang (untuk kode server ) atau pengguna membuat input (untuk kode klien), lalu langkah demi langkah menjelaskan semua lapisan kode yang terlibat.

Cara lain adalah "tur berpemandu" dari kode sumber, yaitu melalui paket / namespaces / modules / direktori dan jelaskan apa yang dilakukan oleh kode pada masing-masing kode secara umum. Tentu saja ini membutuhkan kode yang harus ditata agak logis.

Anda tidak mengajari mereka basis kode, Anda mengajari mereka pekerjaan Anda . Jangan mencoba memikirkan apa yang mungkin mereka butuhkan, lihat apa yang sebenarnya perlu Anda ketahui ketika melakukan pekerjaan Anda.

Tarik beberapa bulan terakhir dari riwayat pelacak bug, scrum cerita pengguna, laporan status, dan komit kontrol sumber. File apa yang paling Anda sentuh? Kode apa yang paling bermasalah? Tugas apa yang paling lama Anda lakukan? Kemungkinannya adalah, jika Anda belum menyentuhnya dalam beberapa bulan terakhir, itu tidak sepenting yang Anda kira.

Lihatlah tumpukan cetakan di meja Anda. Periksa riwayat browser terbaru Anda. Cari email tersimpan yang sering Anda lihat, kontak yang Anda gunakan, dokumen yang telah Anda unduh. Beberapa referensi paling berguna yang saya sampaikan kepada orang lain adalah catatan yang saya simpan untuk diri saya sendiri ketika pertama kali belajar atau merancang sistem. Bahan referensi apa yang paling berguna bagi Anda ?

Selanjutnya tarik backlog Anda yang dikenal. Hal-hal apa yang perlu Anda teliti untuk menyelesaikan tugas-tugas itu? Area kode apa yang paling mungkin mengandung masalah? Sampaikan informasi itu seolah-olah Anda sedang membuat catatan untuk diri sendiri.

Jika Anda merujuk pada bagan atau diagram dalam pekerjaan sehari-hari Anda, sertakan itu. Jika Anda tidak pernah repot membuatnya, itu mungkin tidak akan berguna bagi penerus / kolega Anda.

Salah satu tugas paling sulit ketika mengajar adalah mencoba menempatkan diri Anda pada posisi mereka. Dalam hal ini, Anda berada di posisi mereka. Manfaatkan sebaik-baiknya.

Pekerjaan pendukung adalah yang terbaik, ambil bug yang mudah, dan ajak mereka melewati area di mana ia akan ditemukan. mereka akan dengan cepat belajar bagaimana kode tersebut cocok. Secara alami, mereka akan datang untuk mengajukan pertanyaan tentang bug dan basis kode ini, tetapi mereka akan sampai di sana (dan Anda akan memperbaiki bug). Seringkali lebih mudah untuk mencari tahu dengan contoh, demikian pula, lebih mudah untuk menyusun basis kode dengan menjalankannya dalam debugger.

Jika Anda tidak yakin dengan perubahan kode (atau itu, biasanya saya tidak yakin dengan perbaikan kode saya sampai saya terbiasa dengan basis kode) maka Anda dapat memeriksanya sebelum checkin.

Tentu saja, gagasan Anda tentang ikhtisar luas dan diagram blok adalah langkah awal yang penting.