Bagaimana cara mempromosikan penggunaan kembali dan dokumentasi kode? [Tutup]

Sebagai pemimpin tim sekitar 10+ pengembang, saya ingin mempromosikan penggunaan kembali kode. Kami telah menulis banyak kode - banyak dari mereka berulang selama beberapa tahun terakhir. Masalahnya sekarang adalah bahwa banyak dari kode-kode ini hanya duplikat dari beberapa kode lain atau sedikit variasi dari mereka.

Saya telah memulai gerakan (diskusi) tentang bagaimana membuat kode menjadi komponen sehingga mereka dapat digunakan kembali untuk proyek-proyek masa depan, tetapi masalahnya adalah bahwa saya takut pengembang baru atau pengembang lain yang tidak mengetahui komponen hanya akan maju dan tuliskan sendiri.

Apakah ada untuk mengingatkan pengembang untuk menggunakan kembali komponen / meningkatkan dokumentasi / berkontribusi pada komponen yang mendasarinya alih-alih menduplikasi kode yang ada dan mengutak-atik atau hanya menulis sendiri?

Bagaimana membuat komponen mudah ditemukan, mudah digunakan sehingga semua orang akan menggunakannya?

Saya pikir setiap pengembang tahu tentang manfaat komponen yang dapat digunakan kembali dan ingin menggunakannya, hanya saja kita tidak tahu cara membuatnya dapat ditemukan. Juga, pengembang ketika mereka menulis kode, mereka tahu mereka harus menulis kode yang dapat digunakan kembali tetapi kurangnya motivasi untuk melakukannya.

Anda memerlukan dokumentasi, yang tepat. Seharusnya mudah ditemukan dan dinavigasi. Anda juga butuh disiplin. Jika sudah ada solusi yang disediakan di pustaka kode yang dapat digunakan kembali tetapi pengembang memilih untuk menggunakan solusinya sendiri (tanpa alasan yang tepat), Anda harus mengembalikan solusinya dan katakan padanya untuk menggunakan solusi yang ada.

Saya juga setuju dengan komentar Euphoric untuk pertanyaan itu. Seringkali tidak mungkin untuk menggunakan kembali apa pun di antara berbagai proyek (biasanya semua operasi CRUD terlihat sama, tetapi biasanya Anda tidak dapat menggunakannya kembali).

Di samping faktor-faktor yang telah disebutkan "dokumentasi", "mudah ditemukan dan dinavigasi", "disiplin" dan "codereview"

kode resusable harus

• mudah digunakan (= perlu contoh mis. unittests)
• tanpa terlalu banyak dependensi ke modul lain dan
• itu harus memiliki api yang stabil sehingga saya tidak perlu memperbarui aplikasi saya untuk menggunakan perpustakaan.

tanpa dua item terakhir, akan lebih mudah menggunakan "copy & past-inheritance" yang tidak kita inginkan.

Saya pikir cara terbaik untuk benar-benar membuat mereka menggunakan kembali kode adalah motivasi. Jika Anda memasukkan komponen yang dapat digunakan kembali dalam proyek tambahan, seperti yang disarankan Euphoric, lakukan banyak upaya di dalamnya. Di tempat saya bekerja, kami membuat proyek, yang menjalankan serangkaian antarmuka yang telah ditentukan sebelumnya dalam rencana eksekusi yang dapat dikonfigurasi dan menyediakan beberapa layanan (mis. Kelas yang berbeda untuk interaksi DB_, Layanan FTP, ...). Proyek ini sukses besar, karena pengembang kami sebenarnya ingin menggunakan kerangka-mikro, karena menghemat banyak waktu untuk menulis kode boilerplate untuk proyek serupa. Hal yang sama adalah untuk Utilitas-pustaka untuk Daftar, String, dll, tetapi dalam hal ini Anda ingin menggunakan yang sudah ada. (Mengapa menemukan kembali weel?)

Kesimpulan: Biarkan pengembang Anda merasakan manfaat dari komponen yang dapat digunakan kembali yang telah diuji dengan baik. Tetapi saya juga setuju dengan jawaban Andrzej Bobak: Banyak hal yang tidak dapat digunakan kembali, karena mereka serupa, tetapi tidak sama.

Ini akan sulit, karena orang suka menulis kode baru untuk komponen sederhana dan mereka suka melakukannya dengan cara mereka . Jauh lebih sulit untuk memanfaatkan solusi yang ada dan memperluasnya, daripada menulis implementasi yang sama sekali baru dengan persyaratan baru. Apa yang perlu Anda lakukan, seperti yang telah dinyatakan, adalah memulai proses peninjauan kode di antara tim untuk membantu mengidentifikasi situasi di mana komponen yang ada seharusnya digunakan / diperluas daripada yang baru.

Anda juga perlu memelihara dokumentasi yang sangat baik dan menyeluruh sehingga orang dapat merujuknya dan dengan mudah menemukan apa yang mereka butuhkan. Jika dokumentasi tidak lengkap atau tidak selaras dengan hal yang asli, orang tidak akan termotivasi untuk mencari atau meningkatkannya.

Sebagai pemimpin tim, Anda juga harus mendorong orang untuk bertanya pada diri sendiri apakah ada komponen serupa sebelum membuat sendiri dan mengarahkan mereka ke dokumentasi sehingga mereka dapat mencarinya. Tentu proses peninjauan kode akan menangkapnya jika seseorang melewatkan komponen yang ada, tetapi bagaimana jika mereka sudah menempatkan 10 jam pengembangan dalam implementasi mereka sendiri? Anda perlu menghindari situasi ini dengan menerapkan perilaku penelitian yang baik dalam tim.

Kami menghadapi masalah ini pada proyek besar yang sedang saya kerjakan. Kami telah memiliki beberapa rotasi pengembang selama beberapa bulan terakhir, itu juga basis kode yang cukup besar dan bahkan mereka yang telah berada di proyek sejak awal tidak tahu setiap inci dari itu.

Sementara kode sering ditulis dengan baik dan dipecah menjadi bagian-bagian kecil dengan tanggung jawab tunggal dan dokumentasinya ada, cukup mudah untuk melewatkan sesuatu yang telah dilakukan. Konvensi penamaan yang konsisten sangat membantu karena mudah untuk mencari sesuatu di IDE apa pun. Dokumentasi mungkin komprehensif tetapi seiring bertambahnya waktu, agak sulit untuk membacanya.

Satu hal yang kami lakukan, menurut pendapat saya, sangat memperbaiki situasi adalah pengenalan sesuatu yang kami sebut pembicaraan Petir . Setiap kali seseorang menulis sepotong kode yang dia percaya harus diketahui oleh tim, presentasi singkat (biasanya 5-15 menit) diatur. Kami mencoba melakukan ini seminggu sekali. Subjek cenderung bervariasi, dari fitur baru dan cara menangani masalah kompleks yang baru-baru ini muncul, melalui pendekatan pengujian / pengkodean, komponen yang dapat digunakan kembali, hingga pembicaraan tentang dasar-dasar aplikasi dan refactoring daripadanya.

Subjek tertentu disebutkan pada pembicaraan serupa di seluruh perusahaan. Kami telah menemukan cara yang cukup efisien untuk memacu berbagi pengetahuan. Jauh lebih mudah untuk melihat dan mengingat presentasi singkat dan tahu di mana mencari dokumentasi tambahan atau siapa yang harus ditolong daripada berpartisipasi dalam sesi pelatihan yang sangat lama dan jarang diadakan atau hanya duduk di sana, membaca dokumen dari depan hingga belakang.

Pembicaraan di seluruh perusahaan sebenarnya didahulukan. Kami baru saja mengadopsi pendekatan ini untuk berbagi pengetahuan khusus proyek dan saya pikir itu bekerja dengan cukup baik.

Pemrograman pasangan juga membuat sirkulasi pengetahuan jauh lebih cepat.

Saya pikir ini sebenarnya dua pertanyaan dalam satu - saya akan mencoba menjawab keduanya.

1) Bagaimana kita mengurangi kode duplikat dalam basis kode.
Ini membantu untuk mengingatkan diri kita sendiri tentang manfaat melakukan hal ini: ini menghasilkan bug lebih sedikit karena duplikat logika bisnis dan lebih sedikit kode yang perlu dipertahankan. Cara terbaik untuk mengurangi hal ini terjadi adalah melalui komunikasi - sebagaimana disebutkan dalam jawaban lain. Saya sangat setuju dengan rekomendasi untuk menggunakan ulasan kode dengan peringatan tambahan bahwa Anda harus berbagi tanggung jawab meninjau kode secara adil untuk menyebarkan pengetahuan. Anda juga harus menggunakan stand-up harian sehingga pengembang akan sering mengenali ketika seseorang mencoba memecahkan masalah yang ada kode berguna yang ada. Anda juga harus mempertimbangkan pemasangan kode karena meningkatkan berbagi pengetahuan dan membantu menjaga programer disiplin.

Saya juga merekomendasikan agar pengembang Anda sedekat mungkin, lebih disukai di ruangan yang sama. Dengan banyak whiteboard dan ruang bersama. Kemudian kirim mereka untuk makan bersama. Semakin banyak "ikatan" pengembang Anda, semakin baik mereka berkomunikasi satu sama lain.

Saya tidak setuju dengan rekomendasi untuk menggunakan wiki atau mirip dengan kode dokumen. Tidak peduli seberapa disiplin pengembang mencoba menjadi dokumentasi akan melayang dari kode asli. Pendekatan yang lebih efektif adalah penggunaan spesifikasi dengan uji gaya contoh. Ini mendokumentasikan kode dengan cara yang membuatnya jelas bagaimana harus digunakan dan tes Anda akan gagal jika seseorang mengubah kode tanpa mengubah contoh.

Anda sudah memiliki basis kode besar dengan banyak kode duplikat sehingga Anda mungkin harus bekerja pada refactoring ini. Mungkin sulit menemukan kode duplikat yang tidak dipotong dan disisipkan. Jadi daripada melakukannya saya sarankan Anda menganalisis riwayat perubahan Anda. Cari file yang sering berubah secara bersamaan. Ini mungkin akan menunjukkan masalah dengan enkapsulasi jika tidak menunjukkan kode duplikat yang sebenarnya dan tetap layak untuk dibersihkan. Jika Anda juga dapat menganalisis riwayat perbaikan bug terhadap perubahan kode Anda, Anda mungkin menemukan hotspot tertentu di mana perbaikan sering diperlukan. Analisis hotspot ini dan Anda mungkin akan menemukan banyak di antaranya karena duplikat logika bisnis yang hanya diubah oleh pengembang di satu tempat yang tidak disadari perlu diubah dua kali.

2) Bagaimana kita mendekati membuat widget bersama, komponen, perpustakaan, dll yang kemudian dapat digunakan dalam proyek lain .
Dalam hal ini Anda tidak boleh mencoba untuk membungkus logika bisnis tetapi berbagi kode kerangka yang berguna. Ini bisa menjadi keseimbangan yang rumit karena biaya pembuatan dan pemeliharaan satu set komponen bersama bisa sangat besar dan bisa sulit untuk diprediksi dalam hal mana hal itu layak dilakukan. Pendekatan yang saya sarankan di sini adalah aturan tiga pukulan. Jangan khawatir tentang penulisan kode yang serupa dua kali, tetapi ketika Anda harus melakukannya, refactor ketiga kalinya menjadi komponen bersama. Pada titik ini Anda dapat yakin itu akan berguna dan Anda memiliki ide bagus tentang persyaratan yang lebih luas untuk komponen. Jelas, komunikasi antara pengembang sangat penting di sini.

Pertimbangkan membuat sebanyak mungkin open source komponen bersama Anda. Ini bukan logika bisnis sehingga tidak akan memberi banyak keuntungan bagi pesaing Anda, tetapi itu berarti Anda akan mendapatkan pengulas dan pengelola tambahan secara gratis.

IMMO kuncinya bukan dokumentasi atau alat, kuncinya adalah KOMUNIKASI. 10+ pengembangnya tidak banyak, beberapa hal yang meningkatkan komunikasi ini:

• pemrograman pasangan: dengan dua orang ada lebih banyak perubahan yang salah satu dari keduanya tahu bahwa masalahnya sudah diselesaikan di bagian lain dari proyek dan menggunakannya kembali.

• Kepemilikan kode kolektif: Semua orang bekerja dengan bagian sistem yang berbeda, dengan cara ini jauh lebih mudah bahwa mereka tahu bahwa sesuatu sudah dilakukan di bagian lain dari proyek, bagi saya ini adalah praktik mendasar dalam sebuah tim.

• Berikan waktu untuk mengerjakan proyek horizontal: misalnya, satu atau dua hari Jumat dalam sebulan, dan pengembang saat ini dapat bekerja dalam proyeknya sendiri yang memiliki beberapa penerapan pada proyek perusahaan Anda. Dengan cara ini pengembang dapat menulis pustaka dan komponen yang dapat digunakan kembali, terkadang kodenya sudah ada tetapi perlu pembersihan dan dokumentasi.

• Buat pembicaraan dan lokakarya: Cadangan waktu untuk pembicaraan dan lokakarya pengembang, pengembang dapat berbicara tentang perpustakaannya atau mungkin Anda dapat melakukan lokakarya refactor dan mengambil beberapa kode duplikat dan menghapus duplikasi membuat komponen yang dapat digunakan kembali.

Dokumentasi mungkin diperlukan tetapi hanya sebagian kecil dari hal nyata yang Anda butuhkan: tingkatkan komunikasi di dalam tim Anda.

Bagaimana dengan menggunakan mesin pencari lokal seperti Lucene (atau sesuatu yang lebih spesifik untuk kode sumber) untuk mengindeks kode Anda? Ketika seseorang mulai menulis kelas baru atau fungsi baru (misalnya) ia harus mencoba (sebagai kebijakan internal) beberapa pencarian sebelum menulis kode sendiri. Dengan cara ini Anda dapat menghindari terlalu banyak komunikasi dan Anda dapat mengandalkan komentar, metode, dan nama kelas yang baik. Saya menemukan diri saya melakukan ini dengan mesin pencari open source yang tersedia di internet: Saya tidak tahu siapa yang menulis apa atau apa nama metode atau kelas, tetapi dengan beberapa pencarian atau sinonim saya selalu menemukan apa yang saya butuhkan.

Anda memerlukan alat yang membantu pengembang Anda melakukannya dengan mulus. Jika pengembang Anda menemukan berapa banyak waktu yang dapat dihemat dengan menggunakan kembali cuplikan kode (tidak hanya dalam hal menulis kode, tetapi jelas untuk jaminan kualitas, integrasi, dll.), Dibantu oleh alat yang efisien yang mudah digunakan dan langsung diintegrasikan ke dalam lingkungan pengembangan, mereka akan berdoa Anda untuk mengadopsi alat seperti itu!

Berhati-hatilah bahwa banyak kali realisasi perpustakaan untuk penggunaan kembali kode tidak akan menghasilkan keuntungan besar (mereka cenderung menjadi terlalu kuat dan besar ...); alih-alih, saya ingin fokus pada cuplikan sederhana, yaitu beberapa baris kode yang menyelesaikan tugas tertentu secara efektif.

Dengan cara ini Anda dapat memaksa penggunaan pedoman dan praktik terbaik dengan memberikan contoh nyata yang dapat langsung digunakan oleh programmer.

Ada beberapa alat untuk manajemen snippet, saya sarankan yang ini: http://www.snip2code.com .

(Penafian: Saya salah satu pendiri Snip2Code, dan saya - bersama dengan rekan pendiri saya - dalam pola pikir Anda yang sama beberapa waktu lalu: inilah mengapa kami memutuskan untuk memulai proyek ini, yang mengumpulkan semua fitur yang saya miliki dinyatakan di atas, yaitu berbagi cuplikan di antara tim, integrasi dalam IDE seperti Visual Studio, Eclipse, IntelliJ, Notepad ++, dll.)