Bagaimana proyek open source bisa berhasil tanpa dokumentasi tentang desain atau arsitekturnya?

11

Saya ingin meningkatkan keterampilan pemrograman saya dengan mempelajari proyek-proyek open source yang terkenal, tetapi saya merasa mudah tersesat hanya dengan melompat ke kode sumber mereka.

Jadi saya memutuskan untuk membaca dokumentasi mereka tentang desain atau arsitektur mereka (seperti diagram UML) untuk mendapatkan ide umum tentang organisasi kode mereka terlebih dahulu. Namun, yang mengejutkan saya, saya tidak dapat menemukan dokumentasi arsitektur untuk proyek open source besar seperti Hibernate, Spring, ASP.NET MVC, Rails, dll.

Jadi saya mulai bertanya-tanya: Bagaimana proyek open source dapat berhasil jika pengembang pendatang baru tidak memiliki dokumentasi arsitektur / desain untuk dibaca, atau jika manajer proyek hanya membuka kode sumber tetapi menutup dokumentasinya?

TomCaps
sumber
3
"paling"? Bisakah Anda mendukung ini dengan statistik konkret? Berapa banyak yang Anda baca? Ada berapa banyak? Berapa banyak yang tidak memiliki dokumentasi yang sesuai? Jika Anda tidak memiliki angka, harap hapus kata-kata seperti "kebanyakan" dan ganti dengan fakta nyata berdasarkan apa yang Anda temukan. Selain itu, harap gunakan huruf kapital "Saya" saat merujuk pada diri Anda.
S.Lott
@ S.Lott Maaf untuk "sebagian" subyektif. Saya seorang pemula dalam industri perangkat lunak. Saya mencoba mencari dokumen yang telah saya dengar selama sekolah tinggi (seperti Diagram UML, Diagram Alir, Dokumen Desain Singkat, Dokumen Desain Terpisah, dll) untuk proyek-proyek yang disebutkan baik di situs web proyek mereka atau tempat penyimpanan kode tetapi tidak berhasil, hanya untuk menemukan beberapa dokumen panduan pengguna. Bisakah Anda mengajari saya beberapa cara umum untuk mencari dokumen desgin / archiecture mereka?
TomCaps
1
Harap hapus "Banyak". Itu sama salahnya dengan kebanyakan. silakan memperbarui pertanyaan untuk secara khusus daftar proyek-proyek open source tertentu yang secara khusus tidak memiliki dokumentasi yang spesifik yang ingin Anda lihat. Harap tepat dan spesifik. Tolong jangan bersikap subjektif dan tidak jelas.
S.Lott
Saya menduga bahwa alasan ASP.NET MVC tidak menyertakan diagram UML adalah karena Visual Studio dapat membuatnya dari kode sumber.
user16764
5
Anda beroperasi di bawah asumsi yang salah bahwa "giat" adalah hal yang baik. Apa yang Anda pelajari di perguruan tinggi tentang desain adalah dusta: UML sama sekali tidak bernilai. Saat membuat proyek, yang Anda butuhkan hanyalah gagasan umum tentang apa yang harus dilakukan dan kemauan untuk membuangnya jika Anda salah melakukannya pertama kali. Untuk proyek yang sudah ada, hanya membaca sekilas header utama biasanya cukup untuk mendapatkan ide yang baik tentang tata letak proyek.
o11c

Jawaban:

10

mengapa proyek open source dapat menjadi sukses jika pengembang pendatang baru tidak memiliki dokumen arsitektur / desain untuk dibaca?

Asumsinya selalu membuat Anda tahu apa yang Anda lakukan dan memiliki pemahaman yang cukup intim tentang apa yang akan Anda (dan harapkan) lihat.

Jika Anda melihat kode PHP kerangka kerja Symfony, misalnya, Anda diharapkan sudah tahu tentang injeksi dependensi, peristiwa, pola model / view / controller, dan sebagainya.

Demikian juga, jika Anda menyelami kode C dari kernel linux, asumsinya adalah bahwa Anda akan benar-benar kompeten dalam modularitas, sinyal, proses, utas dan apa yang tidak. Anda juga diharapkan memiliki bakat untuk makan heksadesimal sepanjang hari dan menggali melalui dump inti dengan sekop raksasa.

Pemelihara tidak akan melalui kesulitan mendokumentasikan arsitektur karena itu adalah hal yang sebenarnya. Kadang-kadang, Anda akan menemukan garis besar apa yang ada di mana di pohon sumber. Lebih khusus lagi, cara pohon sumber diatur membuat segala sesuatunya jelas.

Singkatnya, jika Anda tidak memiliki keterampilan yang diharapkan oleh pengelola Anda tahu pada saat Anda mengintip kode mereka, Anda mungkin menggali hal-hal yang jauh di atas nilai gaji Anda. Biasakan diri Anda dengan konsep-konsepnya dulu - Apa model MVC? Apa itu injeksi ketergantungan? Dll. Kemudian menyelam.

Denis de Bernardy
sumber
1
Meskipun jika Anda melihat milis kernel Linux memiliki diskusi luas tentang arsitektur setiap kali seseorang memiliki masalah atau ingin mengubah sesuatu. Ada juga beberapa dokumen yang ditulis tentang hal itu - meskipun tidak di pohon sumber kernel itu sendiri.
edA-qa mort-ora-y
17

Sebagian besar proyek open source yang sukses menjadi sukses karena pertama dan terpenting, program itu mengesankan atau melakukan sesuatu yang tidak bisa dilakukan oleh program lain pada saat itu. Itu tidak berarti sumbernya terdokumentasi dengan baik, karena pemrogram yang memulai proyek untuk mulai mengetahui kode dengan cukup baik sehingga tidak membutuhkannya. Ini adalah kenyataan yang disayangkan bahwa proyek-proyek sumber terbuka tidak harus didokumentasikan dengan baik. Entah itu harus menjadi program yang baik atau menjadi program yang biasa-biasa saja tetapi didokumentasikan dengan baik untuk programmer untuk menyatakan minat di dalamnya.

Neil
sumber
Di perusahaan saya, itu adalah prosedur persyaratan bahwa pengembang harus memberikan Dokumen Desain Rinci sebelum disetujui menulis kode apa pun pada proyek. Apakah prosedur ini tidak normal untuk proyek sumber terbuka?
TomCaps
5
@ TomCaps Saya pikir alasan terbesar bahwa begitu sedikit proyek FOSS memiliki dokumentasi yang luas cukup sederhana: jika Anda menulis sedikit program untuk menyelesaikan kebutuhan yang Anda miliki, kemungkinan karena pengembang Anda yang tidak memerlukan dokumentasi, Anda akan ingin menghabiskan waktu Anda memperbaiki program daripada menulis dokumentasi yang bahkan tidak dijamin bermanfaat bagi siapa pun (bagaimana jika proyek tidak pernah digunakan oleh siapa pun kecuali pengembang?). Ini bukan praktik terbaik, tetapi banyak proyek FOSS kekurangan waktu pengembang.
Jeff Welling
5
@ TomCaps: Prosedur ini tidak normal untuk sebagian besar perusahaan yang saya tahu ...
Treb
1
Kebanyakan proyek open source bukan perusahaan. Anda sedang memikirkan apa yang terjadi ketika ada proyek yang saya dibayar untuk dibangun, dengan tenggat waktu dan anggaran. Jika Anda memiliki banyak orang yang menyandi untuk memenuhi kebutuhan mereka atau untuk bersenang-senang dan tidak ada anggaran atau klien, Anda tidak memiliki hal-hal semacam itu.
Elin
1
@ TomCaps - siapa pun yang menulis perangkat lunak Open Source dapat melakukan apa yang mereka suka. Beberapa proyek (misalnya keluarga Apache) memiliki aturan dan pedoman untuk siapa pun yang melakukan kode dan kadang-kadang ini termasuk standar doumentation dll. Saya juga akan mempertanyakan nilai "dokumen desain detail" karena ini akan selalu mengunci Anda ke dalam desain fisik yang (dalam pengalaman pribadi saya) biasanya kurang optimal. Deskripsi terperinci tentang "apa" yang seharusnya dilakukan oleh program membuat pengembang bebas untuk mengoptimalkan implementasi dan menerapkan strategi kreatif untuk solusinya.
James Anderson
12

Karena pengembang open source biasanya berbakat dan juga memilih proyek di bidang keahlian mereka, mereka sudah memiliki "dokumentasi" di dalam tengkorak mereka. Dengan sedikit berlebihan dokumentasi menyeluruh dibutuhkan hanya jika Anda tidak memilikinya: o)

Sejujurnya, saya tidak benar-benar membaca "dokumentasi" ketika menghadapi basis kode yang tidak dikenal. Pengantar cepat, mungkin beberapa sketsa konseptual dan langsung ke kode! Eksperimen, coba perubahan kecil. Bekerja dengan sempurna untuk kode yang dirancang dengan baik. Jika saya menghadapi kekacauan yang mengerikan, maka cara terbaik untuk mempelajarinya adalah dengan refactor sedikit demi sedikit untuk meningkatkan kejelasan (idealnya dengan bantuan unit-testing).

Alasan tambahan bisa menjadi akar desain organik polos dari proyek-proyek ini. Arsitektur kemudian berevolusi visi dalam pikiran pengembang daripada entitas "didokumentasikan".

Merusak
sumber
8

Alasan mengapa dokumen seperti itu sering tidak ada cukup sederhana: Pemrogram suka memprogram, bukan menulis dokumentasi. Terutama dengan proyek sumber terbuka, yang sering disumbangkan pengembang selama waktu senggang / bebas.

Pada dasarnya, menulis dokumentasi tidak menyenangkan. Dan jika mereka tidak dibayar untuk itu, siapa yang mau menghabiskan waktu luang mereka melakukan sesuatu yang tidak menyenangkan?

GrandmasterB
sumber
Beberapa proyek sumber terbuka besar (GCC, kernel Linux, Firefox, Qt, ....) memiliki sebagian besar (atau sebagian besar) dari kontributor mereka yang dibayar untuk bekerja (penuh waktu atau setengah waktu) pada proyek. Jadi, bahkan ketika dibayar untuk perangkat lunak gratis, mereka tidak menulis banyak dokumentasi
Basile Starynkevitch