Mengapa tidak ada ikhtisar kode untuk proyek sumber terbuka? [Tutup]

Ada proyek open source yang sangat kompleks di luar sana, dan bagi beberapa dari mereka saya pikir saya dapat memberikan kontribusi, dan saya berharap saya bisa, tetapi penghalang untuk masuk terlalu tinggi untuk satu alasan: untuk mengubah satu baris kode pada proyek besar Anda harus memahami semua itu.

Anda tidak perlu membaca semua kode (bahkan jika Anda membaca, itu tidak akan cukup) dan memahami semua setiap baris melakukannya dan mengapa, karena kode mungkin dimodulasi dan dikotak-kotakkan, sehingga ada abstraksi di tempat, tetapi bahkan kemudian Anda perlu mendapatkan gambaran umum proyek sehingga Anda dapat mengetahui di mana modul-modulnya, di mana satu modul saling berhubungan dengan modul lainnya, apa sebenarnya yang dilakukan setiap modul dan mengapa , dan di mana direktori dan file masing-masing hal ini terjadi.

Saya menyebut tinjauan umum kode ini , sebagai nama bagian yang dapat dimiliki proyek open source di situs web atau dokumentasi yang menjelaskan kode mereka kepada orang luar. Saya pikir itu akan menguntungkan kontributor potensial , karena mereka akan dapat mengidentifikasi tempat-tempat di mana mereka dapat membangun, coders utama yang sebenarnya terlibat, karena mereka akan dapat, sambil menulis semuanya, mengatur ulang pikiran mereka, dan akan membantu pengguna , seperti mereka akan menjadi bantuan untuk memahami dan melaporkan bug yang lebih baik yang mereka alami dan bahkan mungkin menjadi kontributor.

Tapi saya masih belum pernah melihat salah satu dari "tinjauan kode" ini. Mengapa? Apakah ada hal-hal seperti ini dan saya kehilangan mereka? Hal-hal yang melakukan pekerjaan yang sama dengan yang saya jelaskan? Atau apakah ini ide yang sama sekali tidak berguna, karena semua orang, kecuali saya, dapat memahami proyek dengan ribuan baris kode dengan mudah?

Karena ini merupakan upaya ekstra untuk membuat dan memelihara dokumen seperti itu, dan terlalu banyak orang tidak memahami manfaat yang terkait.

Banyak programmer yang bukan penulis teknis yang baik (walaupun banyak yang); mereka jarang menulis dokumen hanya untuk konsumsi manusia, oleh karena itu mereka tidak memiliki praktik dan tidak suka melakukannya. Menulis tinjauan kode membutuhkan waktu yang tidak dapat Anda habiskan untuk pengkodean, dan manfaat awal untuk sebuah proyek selalu lebih besar jika Anda dapat mengatakan "Kami mendukung ketiga varian penyandian" daripada "Kami memiliki penjelasan yang sangat rapi tentang kode kami!" Gagasan bahwa dokumen semacam itu akan menarik lebih banyak pengembang sehingga dalam jangka panjang lebih banyak kode akan ditulis tidak persis asing bagi mereka, tetapi dianggap sebagai pertaruhan yang tidak pasti; Akankah teks ini benar-benar membuat perbedaan antara menjepit kolaborator atau tidak? Jika saya terus mengkode sekarang , selesaikan hal ini.

Dokumen tinjauan kode juga dapat membuat orang merasa defensif; sulit untuk menggambarkan keputusan tingkat yang lebih tinggi tanpa merasa perlu untuk membenarkannya, dan sangat sering orang membuat keputusan tanpa alasan yang "terdengar cukup baik" ketika sebenarnya ditulis sendiri. Ada juga efek yang terkait dengan yang disebutkan di atas: karena memperbarui teks yang sesuai dengan kode perubahan menyebabkan upaya tambahan, ini dapat mencegah perubahan besar pada kode. Terkadang stabilitas ini adalah hal yang baik, tetapi jika kode benar-benar membutuhkan penulisan ulang tingkat menengah, itu berubah menjadi kewajiban.

Kebenaran yang kering dan keras?

Dokumentasi tidak dibuat karena proyek dapat dilakukan tanpanya.

Bahkan proyek open source sering menghadapi persaingan yang ketat. Sebagian besar proyek semacam itu tidak dimulai dengan pundak besar, mereka memulai sebuah ide cemerlang, seringkali ide cemerlang satu orang.

Karena itu, mereka tidak mampu membayar waktu dan biaya untuk menyewa pendokumentasi manusia, bahkan jika mereka menawarkan untuk bekerja sama secara gratis. Sebuah proyek yang terdokumentasi, infact, biasanya telah melewati beberapa iterasi awal terlebih dahulu. Ini sering dimulai dengan 1-3, mungkin 5 orang menuliskan ide novel mereka dan menunjukkannya kepada dunia sebagai bukti konsep. Jika gagasan terbukti baik maka "pengikut" dapat menambahkan, mereka cenderung mulai meminta ekstensi, opsi baru, terjemahan ... Pada titik ini kode tersebut masih berupa prototipe, biasanya dengan opsi dan pesan yang dikodekan secara keras.

Tidak semua proyek open source melampaui fase ini, hanya proyek yang mematahkan "massa kritis" yang diperlukan untuk menarik minat publik. Selain itu, salah satu pengembang awal harus "berpikir besar dan jauh" dan merencanakan ekspansi dan sebagainya. Dia mungkin juga menjadi "penginjil" proyek dan kadang-kadang juga "manajer proyek" (kadang-kadang orang yang berbeda). Itu adalah langkah yang diperlukan untuk meningkatkan proyek, dari pembuktian konsep menjadi kenyataan yang ditetapkan industri.

Bahkan kemudian, manajer proyek dapat memilih untuk tidak membuat dokumentasi.

Proyek yang dinamis dan berkembang akan diperlambat dan dokumentasi akan benar-benar tertinggal di belakang kode sementara itu ditingkatkan sangat keras, untuk mengimplementasikan terjemahan, opsi, tancapkan manajer ...

Apa yang biasanya terjadi adalah:

1. Dokumen pengantar singkat dibuat, tentang apa proyek itu dan ke mana arahnya ("peta jalan" yang terkenal).
2. Jika memungkinkan, API dikembangkan dan yang dipilih sebagai "kode terdokumentasi" di atas sebagian besar kode yang mendasarinya.
3. Terutama API tetapi juga kode lainnya diformat ulang dan "PHPdoc" / "Javadoc" dll. Komentar khusus ditambahkan. Mereka menawarkan kompromi yang layak antara waktu yang dihabiskan dan penghargaan: bahkan seorang programmer sederhana biasanya tahu bagaimana menulis satu liner yang menggambarkan fungsinya, parameter mendapatkan "auto" didokumentasikan juga dan keseluruhan terikat dengan kode yang terkait dan dengan demikian mereka menghindari dokumentasi " desyncing "dan pengembangan behing lagging.
4. Paling sering, sebuah forum dibuat. Ini adalah media sosial yang kuat di mana pengguna dan pemrogram akhir dapat berbicara satu sama lain (dan di antara rekan-rekan mereka, mungkin dalam subforum "devs only"). Hal ini memungkinkan banyak pengetahuan muncul secara perlahan dan dikonsolidasikan oleh komunitas yang dibuat (baca: tidak membebani tim pengembang). FAQ dan HOWTO.
5. Dalam proyek yang sangat besar, wiki juga diproduksi. Saya menyatakan "proyek-proyek besar" karena mereka sering kali adalah mereka yang memiliki cukup pengikut untuk membuat wiki (dev tidak) dan kemudian benar-benar mengisinya di luar "tulang telanjang" (komunitas melakukannya).

Dokumen tinjauan umum seperti yang Anda gambarkan jarang ada di proyek komersial. Mereka membutuhkan upaya ekstra dengan sedikit nilai untuk pengembang. Juga pengembang cenderung tidak menulis dokumentasi kecuali mereka benar-benar perlu. Beberapa proyek beruntung memiliki anggota yang pandai menulis teknis, dan sebagai hasilnya memiliki dokumentasi pengguna yang baik. Dokumentasi pengembang jika ada, tidak mungkin diperbarui untuk mencerminkan perubahan kode.

Setiap proyek yang terorganisir dengan baik akan memiliki pohon direktori yang cukup jelas. Beberapa proyek akan mendokumentasikan hierarki ini dan / atau alasan dipilihnya. Banyak proyek mengikuti tata letak kode yang relatif standar, jadi jika Anda memahaminya, Anda akan memahami tata letak proyek lain menggunakan tata letak yang sama.

Untuk mengubah sebaris kode, Anda memerlukan pemahaman terbatas tentang kode di sekitarnya. Anda seharusnya tidak perlu memahami seluruh basis kode untuk melakukannya. Jika Anda memiliki ide yang masuk akal tentang jenis fungsi yang rusak, seringkali dimungkinkan untuk menavigasi hierarki direktori dengan lebih cepat.

Untuk mengubah satu baris kode Anda perlu memahami metode di mana baris tersebut ditemukan. Jika Anda memahami apa perilaku yang diharapkan dari metode ini, Anda harus dapat membuat perubahan korektif, atau ekstensi ke fungsionalitas.

Untuk bahasa yang menyediakan pelingkupan, Anda dapat memperbaiki metode pelingkupan privat. Dalam hal ini Anda mungkin perlu mengubah penelepon serta metode atau metode refactor. Ini membutuhkan pemahaman yang lebih luas, tetapi masih terbatas, tentang basis kode.

Lihat artikel saya Menambahkan SHA-2 ke tinyca untuk contoh bagaimana perubahan tersebut dapat dilakukan. Saya memiliki pemahaman yang sangat terbatas tentang kode yang digunakan untuk menghasilkan antarmuka.

Apakah ada hal-hal seperti ini dan saya kehilangan mereka? Hal-hal yang melakukan pekerjaan yang sama dengan yang saya jelaskan?

Ada sebuah buku bagus yang disebut Arsitektur Aplikasi Sumber Terbuka yang memberikan deskripsi terperinci tentang berbagai proyek perangkat lunak sumber terbuka profil tinggi. Namun, saya tidak yakin apakah itu persis mengisi peran yang Anda bayangkan, karena saya percaya audiens utamanya dimaksudkan untuk menjadi pengembang yang mencari pola untuk diikuti saat membuat aplikasi mereka sendiri, bukan kontributor baru untuk proyek-proyek yang ditampilkan dalam buku ini. (meskipun saya yakin itu bisa membantu di sana).

Karena ada jauh lebih banyak programmer open-source daripada penulis teknis open-source.

Dokumentasi membutuhkan perawatan dan waktu untuk tetap mendapatkan informasi terbaru. Semakin banyak dokumentasi, semakin banyak yang dibutuhkan. Dan dokumentasi yang tidak selaras dengan kode lebih buruk daripada tidak berguna: itu menyesatkan dan menyembunyikan bukannya mengungkapkan.

Basis kode yang terdokumentasi dengan baik lebih baik dari pada yang kurang terdokumentasi, tetapi dokumentasi dapat dengan mudah memakan waktu selama menulis kode. Jadi pertanyaan Anda adalah, apakah lebih baik memiliki basis kode yang terdokumentasi dengan baik, atau basis kode yang dua kali lebih besar? Apakah biaya untuk memperbarui dokumentasi setiap kali kode perubahan sepadan dengan kontribusi pengembang tambahan yang mungkin atau tidak dapat dihasilkannya?

Kode pengiriman menang. Mengurangi jumlah upaya yang dimasukkan ke dalam hal-hal selain kode pengiriman dapat membuat pengiriman kode lebih sering, dan lebih mungkin untuk dikirim sebelum kehabisan sumber daya.

Ini tidak berarti bahwa hal-hal selain masalah pengiriman. Dokumentasi menambah nilai bagi proyek, dan dengan proyek yang cukup besar biaya interkoneksi untuk menambah pengembang lain mungkin jauh lebih tinggi daripada menambahkan seorang pendokumentasi. Dan, seperti disebutkan, dokumentasi dapat meningkatkan investasi dalam proyek (dengan membuatnya lebih mudah bagi programmer baru untuk bergabung).

Namun, tidak ada yang menjual seperti kesuksesan: proyek yang tidak berfungsi atau melakukan sesuatu yang menarik jarang menarik pengembang juga.

Dokumentasi basis kode adalah bentuk meta-work. Anda dapat menghabiskan banyak waktu menulis dokumen mewah yang menggambarkan basis kode yang tidak banyak nilainya, atau Anda dapat menghabiskan waktu membuat barang-barang yang diinginkan konsumen dari basis kode Anda dan membuat basis kode Anda memiliki nilai.

Terkadang membuat keadaan menjadi lebih sulit membuat mereka yang melakukan tugas lebih baik. Entah karena tingkat komitmen yang lebih tinggi terhadap proyek (menghabiskan berjam-jam mempelajari arsitektur), atau karena bias keterampilan (jika Anda sudah ahli dalam teknologi terkait, meningkatkan kecepatan akan lebih cepat, sehingga hambatan kurangnya dokumentasi semacam itu kurang penting: sehingga lebih banyak ahli bergabung dengan tim, dan lebih sedikit pemula).

Akhirnya, untuk alasan yang disebutkan di atas, pengembang saat ini cenderung menjadi ahli dalam basis kode. Menulis dokumentasi semacam itu tidak banyak membantu mereka memahami basis kode, karena mereka sudah memiliki pengetahuan, itu hanya membantu pengembang lain. Banyak pengembangan sumber terbuka didasarkan pada "goresan gatal" yang dimiliki pengembang dengan kode: kurangnya dokumentasi yang sudah mengatakan apa yang jarang diketahui pengembang.

Selain sebagai upaya ekstra , beberapa proyek open source melumpuhkan dokumentasi mereka dengan sengaja, untuk mendapatkan pekerjaan lepas bagi para pengelola mereka (untuk mengimplementasikan sesuatu, atau untuk mengadakan pelatihan). Tidak hanya mereka tidak memiliki ikhtisar kode, tetapi API dan tutorial mereka buruk atau banyak hal yang hilang.

Hanya satu nama yang cukup populer: bluez. Semoga berhasil menemukan tutorial yang bagus, selain itu untuk memindai perangkat terdekat.