Bagaimana Anda melacak kelas dan fungsi apa yang telah ditulis tim Anda?

43

Ketika mengerjakan kode, saya menghadapi banyak tantangan yang sama seperti yang dilakukan rekan tim saya, dan saya telah menulis beberapa fungsi dan kelas yang membantu, dan begitu juga mereka. Jika ada komunikasi yang baik, saya akan mendengar tentang beberapa hal hebat yang disatukan seseorang, dan enam bulan kemudian ketika saya membutuhkannya, saya mungkin mengingatnya dan memanggil fungsi itu, menghemat waktu saya sendiri. Jika saya tidak mengingatnya, atau tidak pernah mengetahuinya, saya mungkin akan menemukan kembali kemudi.

Apakah ada praktik khusus untuk mendokumentasikan hal-hal semacam ini? Bagaimana Anda membuatnya mudah ditemukan?

Jika tim Anda tidak memiliki dokumentasi seperti itu, bagaimana Anda mengetahui apakah roda Anda sudah ada?

SUNTING:

Semua kecuali salah satu jawaban sejauh ini berkaitan dengan situasi ideal, jadi izinkan saya meringkas solusi-solusi itu: dokumentasi & komunikasi; wiki, stand-up meeting, dll. Itu semua adalah hal-hal hebat, tetapi mereka bergantung pada programmer yang punya waktu (dan keterampilan) untuk menulis dokumentasi dan menghadiri pertemuan dan membuat catatan dan mengingat semuanya.

Jawaban paling populer sejauh ini (Caleb) adalah satu-satunya yang dapat digunakan oleh seorang programmer yang tidak mampu melakukan dokumentasi dan rapat, dan hanya melakukan satu hal: pemrograman. Pemrograman adalah apa yang dilakukan oleh seorang programmer, dan ya, seorang programmer yang hebat dapat menulis dokumentasi, unit test, dll, tetapi mari kita hadapi itu - kebanyakan dari kita lebih suka pemrograman daripada mendokumentasikan. Solusinya adalah di mana programmer mengenali kode yang dapat digunakan kembali dan menariknya ke kelasnya sendiri atau repositori atau apa pun, dan oleh kenyataan bahwa itu terisolasi, ia menjadi dapat ditemukan dan memudahkan kurva belajar untuk menggunakannya ... dan ini dicapai dengan pemrograman.

Di satu sisi saya melihatnya seperti ini: Saya baru saja menulis tiga fungsi, dan terpikir oleh saya bahwa orang lain harus tahu tentang mereka. Saya bisa mendokumentasikannya, menulisnya, mengumumkannya di rapat, dll - yang bisa saya lakukan, tapi itu bukan kekuatan saya - atau .... Saya bisa mengekstraknya ke kelas, beri nama dengan baik, buat mereka berfungsi seperti kotak hitam, dan tempel di mana file kelas lain pergi. Maka email singkat yang mengumumkannya mudah. Pengembang lain dapat memindai kode dan memahaminya lebih baik daripada fungsi terisolasi yang digunakan dalam kode yang tidak sepenuhnya mereka pahami - konteks itu dihapus.

Saya suka ini karena itu berarti memiliki satu set file kelas yang bernama baik, dengan metode yang dinamai, adalah solusi yang baik yang dicapai oleh pemrograman yang baik. Itu tidak memerlukan pertemuan, dan itu melunakkan kebutuhan untuk dokumentasi rinci.

Apakah ada lebih banyak ide dalam nada ini ... untuk pengembang terisolasi dan waktu?

documentation teamwork team code-reuse changokun
sumber
5
Saya akan memperluas pertanyaan untuk ditanyakan pada skala yang lebih besar, mungkin di perusahaan yang terdiri dari 100 karyawan, bagaimana Anda melakukan hal yang sama. Praktik terbaik apa yang dapat dilakukan untuk menghindari duplikasi pekerjaan yang dilakukan sebelumnya?
Asaf
1
@ Asaf - Saya menduga jawaban yang benar akan tergantung pada ukuran populasi - apa yang bekerja untuk toko 5 orang tidak akan berfungsi untuk 50, dan apa yang berhasil untuk 50 tidak akan berhasil untuk 500. Jawaban untuk semua akan diterima.
Dan Pichelman
3
Ini pertanyaan yang bagus!
Rocklan
4
Hukum Conway : "organisasi yang merancang sistem ... dibatasi untuk menghasilkan desain yang merupakan salinan dari struktur komunikasi organisasi-organisasi ini".
Mark Rushakoff
2
@nathanhayfield: itu adalah solusi yang dapat bekerja untuk 1 dev, dan sedikit banyak untuk 2 dev, tetapi tidak untuk 20 atau 100. Dan bahkan ketika saya bekerja sendiri, saya lebih suka memisahkan fungsi pembantu secara tematis.
Doc Brown

Jawaban:

29

Perpustakaan. Kerangka kerja Kontrol versi.

Jika Anda memiliki kode yang dapat digunakan kembali, hal terakhir yang Anda inginkan adalah anggota tim yang berbeda untuk menyalin kode sumber ke proyek mereka. Jika mereka melakukannya, kemungkinan besar mereka akan berubah sedikit di sini dan mengubah sedikit di sana, dan segera Anda akan memiliki lusinan fungsi atau metode yang semuanya memiliki nama yang sama tetapi masing-masing bekerja sedikit berbeda. Atau, mungkin lebih mungkin, penulis asli akan terus memperbaiki kode untuk memperbaiki bug, membuatnya lebih efisien, atau menambahkan fitur, tetapi kode yang disalin tidak akan pernah diperbarui. Nama teknis untuk itu adalah kekacauan besar .

Solusi yang tepat adalah dengan menarik hal-hal yang dapat digunakan kembali dari proyek apa pun yang Anda bangun untuk itu dan menempatkannya di perpustakaan atau kerangka kerja dalam repositori kontrol versinya sendiri. Itu membuatnya mudah ditemukan, tetapi juga mencegah melakukan perubahan tanpa mempertimbangkan semua proyek lain yang mungkin menggunakannya. Anda mungkin mempertimbangkan memiliki beberapa pustaka yang berbeda: satu untuk kode yang teruji dengan baik yang tidak lagi cenderung berubah, satu untuk hal-hal yang tampaknya stabil tetapi belum diuji dan ditinjau secara menyeluruh, satu untuk penambahan yang diusulkan.

Caleb
sumber
5
Saya juga ingin merekomendasikan memiliki serangkaian uji regresi yang sangat teliti untuk perpustakaan yang dapat digunakan kembali. Bahkan jika perubahan itu tampaknya tidak berbahaya, seseorang mungkin bergantung pada perilaku itu.
Bobson
2
Saya pikir istilah teknisnya BBOM .
zzzzBov
2
Jawaban Anda terdengar masuk akal pada pandangan pertama, dan pada skala kecil hingga menengah, itu, tetapi saya juga melihat sisi gelap dari arahan "jangan salin". Jika Anda memiliki tim yang berbeda untuk produk yang berbeda, dengan ketentuan lisensi yang berbeda, siklus hidup yang berbeda, dan kontrak perawatan yang berbeda, hal terakhir yang Anda inginkan adalah memasangkan produk yang berbeda ke pustaka cuplikan kode yang dibuat sendiri di rumah yang tidak cocok dengan persyaratan pemeliharaan . Perpustakaan untuk skenario seperti itu harus memiliki kualitas yang sangat tinggi, dan kadang-kadang bahkan lebih efisien bagi tim untuk menyalin kode dan ..
Doc Brown
3
@ Caleb: tetap tenang, baca postingan saya sepenuhnya. Maksud saya adalah: menyalin kode dari tempat lain, men-tweak dan mengintegrasikannya ke perpustakaan tim tidak selalu membawa Anda di "jalan menuju kebinasaan". Ketika Anda memiliki dua lib dengan fungsi yang tumpang tindih, dan dua tim yang masing-masing bertanggung jawab untuk menjaga lib mereka, situasinya tidak terlalu buruk. Itu tidak sempurna, karena satu tim dapat melakukan beberapa pekerjaan yang lain juga, tetapi kadang-kadang keuntungan bahwa tim-tim tersebut tetap independen melebihi pekerjaan ganda.
Doc Brown
1
@DocBrown Ada yang situasi di mana menjadi perlu untuk menyalin kode, tapi itu harus menjadi keputusan sadar dan tidak sesuatu yang Anda terpaksa dilakukan karena dari cara di mana kode tersebut dibagikan di tempat pertama.
Caleb
13

Salah satu pendekatan untuk itu adalah menyiapkan Wiki untuk tujuan itu, dan menulis beberapa dokumen tingkat tinggi tentang komponen apa yang dapat digunakan kembali yang Anda miliki, bagaimana Anda memecahkan masalah, dll.

Bagian tersulitnya adalah meminta setiap orang di tim Anda untuk terus memelihara Wiki itu. Tetapi segala jenis dokumentasi lainnya menderita masalah yang sama.

Beberapa kode Anda mungkin juga cukup baik untuk dimasukkan ke pustaka yang dapat digunakan kembali. Ini membuatnya juga lebih mudah untuk menemukan kode lagi nanti.

Doc Brown
sumber
5
Wiki bukanlah cara yang tepat untuk menyebarkan kode. Ini cara yang bagus untuk berkomunikasi tentang kode, tetapi (lihat jawaban saya) Anda tidak ingin orang menyalin sesuatu yang lebih besar dari potongan wiki dan menempelkannya ke proyek mereka.
Caleb
@ Caleb komunikasi adalah bagian yang sulit
jk.
@ jk - Masalah komunikasi bertambah jika Anda tidak memiliki kontrol sumber yang disebutkan dalam C
JeffO
3
@ Caleb: Pertanyaan OP bukan tentang penyebaran kode, pertanyaannya adalah tentang berkomunikasi dan menemukannya nanti.
Doc Brown
@DocBrown Sekali lagi, wiki sangat bagus untuk berkomunikasi, dan itu mungkin mengapa alat seperti GitHub memiliki satu built in. Tetapi hal yang membuat kode mudah ditemukan adalah tidak disebutkan dalam wiki, melainkan disimpan di tempat yang dikenal. Itu bisa berupa wiki, tetapi jika kita berbicara tentang kode yang orang benar-benar akan gunakan (vs. sekelompok cuplikan yang menggambarkan solusi) itu harus berupa semacam perpustakaan, sesuatu yang dapat dibangun, dapat diuji, dan yang dapat dimasukkan tanpa mengalikan jumlah tempat yang cepat atau lambat perlu diperbarui.
Caleb
7

Berada di perusahaan dengan 700 karyawan, dalam tim yang bervariasi antara 2 dan 20 orang, inilah pengalaman saya.

Di level tim

Kami memiliki "pertemuan standup" setiap hari selama sekitar 15-20 menit. Kita dapat dengan cepat berbagi pengetahuan umum seperti "Saya melakukan fungsi ini kemarin, sangat sulit".

Kami juga memiliki wiki per proyek. Yang berarti kami dapat berbagi informasi (teknis) tentang apa yang dilakukan dalam proyek, termasuk kelas / fungsi khusus yang ada di dalamnya.

Di tingkat agensi

Di tingkat agensi, kami memiliki 4 alat:

  • Wiki lain. Itu terutama di sana untuk memberi kita informasi tentang perangkat keras dan barang-barang, tetapi kadang-kadang kita menggunakannya untuk berbagi informasi teknis untuk ditinjau sebelum meletakkannya di tingkat perusahaan.
  • Pertemuan mingguan. Mereka sebagian besar ingin mengetahui kemajuan masing-masing tim / proyek, tetapi karena kami sebagian besar penggemar teknologi, kami dapat mengemukakan hal-hal keren.
  • Milis. Kami memiliki surat dengan semua orang di agensi. Banyak hal-hal keren / hal-hal menyenangkan / hal-hal yang berguna bisa lewat sana
  • Repositori VCS. Setiap agensi memiliki repositori pribadinya di mana kami memiliki proyek-proyek kecil, sebagian besar modul yang kami gunakan dalam proyek yang berbeda.

Di tingkat perusahaan

Di tingkat perusahaan, ini lebih terorganisir.

Wiki "level agensi" sebenarnya adalah bagian dari wiki perusahaan.

Dan wiki kemudian dibagi berdasarkan teknologi. Jadi, siapa pun dapat memperbaikinya, mencari melalui itu, dan pada dasarnya memberi kehidupan kepada wiki.

Ada juga milis yang bisa kami langgani. Siapa pun di agensi dapat berlangganan, dan kebanyakan orang mengikuti setidaknya satu atau dua teknologi, sebenarnya kebanyakan orang mengikuti 5-10 dari mereka.

Dan VCS tentu saja merupakan sistem berbagi kode terbaik.

Kesimpulan

Singkatnya, tidak ada solusi yang jelas. Berbagi pengetahuan selalu menjadi masalah besar, dan mungkin akan tetap ada. Ada banyak solusi untuk membuat basis pengetahuan , dan satu mungkin bisa sesuai dengan tagihan Anda. Namun, beberapa orang berusaha mendapatkan KB yang lebih baik karena solusi saat ini tidak selalu sangat pintar.

Florian Margaine
sumber
Saya merasa bahwa kesimpulannya harus mengatakan tidak lebih dari "wiki, wiki, wiki, wiki, wiki" tetapi pada catatan yang serius, jawaban yang baik, wiki internal bisa baik untuk merinci detail tingkat yang lebih tinggi atau usia penggunaan, belum lagi hanya dicari adalah penghemat waktu yang baik.
RhysW
6

Nah, itu semua bermuara pada komunikasi.

Wiki sangat bagus dan Anda harus menginstal dan menggunakannya. Intranet pemrogram internal yang bagus bagus jika orang membacanya dan memperbaruinya, jadi Anda sebenarnya sedang membicarakan masalah orang di sana. Anda bisa menyarankan pertemuan "pembaruan tim" mingguan di mana semua orang berkumpul dan memberikan ikhtisar tentang apa yang sedang terjadi. Pimpinan teknologi (setidaknya!) Harus berkumpul dan mengobrol tentang apa yang dilakukan masing-masing tim. Sesi informal "Brown Bag" sangat bagus, jadwalkan saat makan siang, dan buat orang berbicara.

Anda juga memerlukan cara berbagi kode, mengemasnya, mengversi dan mendistribusikannya. Hal-hal akan lebih mudah jika Anda memiliki repositori kode sumber yang dikelola dengan sangat baik, diatur dengan baik ke dalam folder "umum" dan proyek.

Jika tidak ada hal seperti ini yang dilakukan, bawalah bos Anda, jelaskan bagaimana itu akan menguntungkan perusahaan dan menyarankan jalan ke depan :)

Rocklan
sumber
1
Saya akan menggerakkan konsep "umum" sedikit lebih jauh dalam jawaban Anda.
JeffO
4

Sesi tinjauan kode dapat membantu. Jika tim Anda bertemu secara teratur untuk membahas apa yang dikembangkan, maka orang yang menemukan solusi dapat menunjukkan kepada orang lain bagaimana menggunakannya. Jika seseorang mengemukakan poin yang mereka pertahankan, anggota tim lain dapat mengusulkan pendekatan yang meningkatkan penggunaan kembali komponen yang ada.

Daenyth
sumber
1
Lalu 4 tahun dan 600 fungsi kemudian ketika Anda ingin mengingat bahwa satu fungsi yang dibuat beberapa waktu? Sebagian dari masalah OP adalah mencoba mengingat semua hal yang telah dibuat, sementara ini bagus awalnya tidak akan bertahan selama periode mungkin, satu atau dua bulan
RhysW
2

Cara terbaik untuk menangani sesuatu seperti itu adalah memiliki struktur repositori yang memiliki beberapa konvensi sederhana sehingga saya tahu, sebagai seorang programmer, jika ada fungsi doXYZ, kira-kira di mana saya harus mencari fungsi itu. Apakah Anda menggunakan ruang nama, direktori, modul, plugin, paket, apa pun, kode Anda harus modular sehingga fungsi yang melakukan hal yang sama atau mengakses sumber data yang sama sebagian besar berada di tempat yang sama.

Jonathan Rich
sumber
0

Idealnya, harus ada setidaknya satu orang lain selain penulis yang melakukan peninjauan kode pada setiap checkin. Proses peninjauan kode dapat membantu mengurangi masalah banyak metode duplikat yang sedang diperiksa. Tentu saja, Anda terkendala oleh pengetahuan pengulas.

TL; DR: Ulasan kode untuk setiap checkin.

Carolyn
sumber
2
Jangan paham. Apakah Anda akan membuang kode yang diuji dan berfungsi hanya karena itu terlihat seperti duplikat dalam ulasan kode? Pertanyaannya adalah bagaimana menghindari menulis kode duplikat di tempat pertama. Sesi seperti jawaban @ daenyth tampaknya lebih baik.
adrianm
Jika pengulas mengatakan kepada saya saya menambahkan kode yang menduplikasi fungsi, dan saya melihat dan menemukan bahwa mereka benar, ya ya saya akan memo kode dupe. (Saya mungkin juga akan memeriksa apakah implementasi saya lebih baik, dan jika demikian, lihat apakah saya dapat memperbaiki implementasi yang lain alih-alih menambahkan yang baru.)
Carolyn