Mengapa begitu banyak perpustakaan yang tidak memiliki / dokumentasi yang buruk? [Tutup]

Dalam nada yang sama seperti Bagaimana proyek open source bisa berhasil tanpa dokumentasi tentang desain atau arsitekturnya? pertanyaan, saya ingin tahu: Mengapa begitu banyak perpustakaan yang kurang dalam dokumentasi pengguna akhir?

Pandangan saya adalah ini:

1. Kebanyakan orang setuju bahwa membaca kode sumber lebih sulit daripada menulis kode sumber.
2. Tanpa dokumentasi, seseorang harus membaca kode sumber perpustakaan untuk menggunakan perpustakaan itu.
3. Oleh karena itu, menggunakan pustaka yang tidak terdokumentasi lebih berfungsi daripada sekadar membuat pustaka dari awal.
4. Akibatnya, jika Anda ingin orang-orang menggunakan perpustakaan Anda, Anda sebaiknya memastikan itu didokumentasikan.

Saya tahu banyak pengembang tidak suka menulis dokumen, dan saya setuju itu bisa jadi pekerjaan yang membosankan. Tapi ini pekerjaan penting. Saya bahkan mengatakan bahwa lebih penting bahwa perpustakaan memiliki dokumentasi yang baik daripada memiliki antarmuka programmer terbaik di dunia. (Orang-orang menggunakan perpustakaan buruk setiap saat; sedikit yang menggunakan perpustakaan tidak berdokumen)

Oh, perhatikan bahwa ketika saya mengatakan dokumentasi, maksud saya dokumentasi nyata. Bukan boilerplate Sandcastle / Javadoc / Doxygen.

Saya pikir Anda sebagian besar telah menjawab pertanyaan Anda sendiri: karena dalam kebanyakan kasus, pengembang tidak akan repot. Masalahnya sangat lazim dalam proyek sukarela.

Saya pikir ada masalah besar lain: dalam banyak kasus, pengembang belum benar-benar mengembangkan model keseluruhan tentang cara kerja perpustakaan mereka (atau hanya mengalami kesulitan mengartikulasikan model itu dengan jelas). Sayangnya, mengartikulasikan model itu dan bagaimana potongan-potongan perangkat lunak cocok bersama seringkali merupakan bagian terpenting dari dokumentasi.

Dalam kasus tertentu, apa yang ditulis memiliki ikhtisar tingkat sangat tinggi ("Ini adalah perpustakaan untuk melakukan hal-hal keren!") Dan kemudian deskripsi tingkat sangat rendah (jenis dan deskripsi setiap parameter untuk diteruskan ke setiap fungsi). Sayangnya, jarang ada tingkat menengah tentang teori umum tentang bagaimana hal-hal yang seharusnya bekerja, bagaimana potongan-potongan itu cocok bersama, dll. Banyak dari ini kembali ke fakta bahwa pengembang sering belum berusaha untuk membentuk, merasionalisasi, atau memahami mereka. kode pada tingkat detail tertentu. Setidaknya dalam beberapa kasus yang saya lihat, pengembang yang diminta untuk menulis dokumentasi pada tingkat itu merasa cukup bermasalah - sampai-sampai banyak yang ingin menulis ulang kode sehingga akan lebih terorganisir dan lebih mudah dijelaskan pada tingkat itu. detail.

Menulis dengan baik pada tingkat abstraksi itu seringkali sulit - dan jika pengembang tidak benar-benar melakukannya memikirkannya pada tingkat abstraksi itu, mereka akan sering menemukan kode itu agak memalukan, dan mungkin ingin menulis ulang sebelum mereka bahagia tentang melepaskannya sama sekali.

Saya pikir kadang-kadang itu karena pengembang begitu terbungkus dalam kode sehingga "jelas" baginya cara kerjanya dan mereka tidak bisa melihat mengapa itu tidak jelas bagi orang lain. Demikian pula, banyak situs web produk mengatakan betapa indahnya produk mereka, tetapi tidak benar-benar memberi tahu Anda apa fungsinya!

Anda menunjukkan jawabannya sendiri:

Saya tahu banyak pengembang tidak suka menulis dokumen, dan saya setuju itu bisa jadi pekerjaan yang membosankan.

Sebagai pemrogram, kami menikmati penulisan kode, tetapi sangat sedikit dari kita yang juga suka menulis dokumentasi.

Sementara setiap pembuat kode yang baik mengetahui nilai dokumentasi yang baik, dibutuhkan waktu yang cukup untuk melakukannya dengan benar. Karena tidak menyenangkan dan membutuhkan waktu yang lama, tumpukan itu dimasukkan ke dalam tumpukan "untuk dikerjakan nanti" sehingga tidak pernah dilakukan pada tingkat yang memuaskan.

Sebagai catatan tambahan, sangat sulit bagi seorang programmer untuk menulis dokumentasi pada produk mereka sendiri. Karena mereka tahu sistemnya dengan baik, hal-hal tertentu jelas bagi mereka. Bagian-bagian ini sering tidak disebutkan meskipun tidak jelas bagi konsumen.

Dokumentasi menulis adalah keterampilan. Seperti semua keterampilan yang dibutuhkan latihan. Waktu dan upaya yang kita habiskan untuk menulis kode memiliki hasil langsung. Kita dapat melihat fitur baru, bug yang diperbaiki, kecepatan yang ditingkatkan. Dokumentasi penulisan memiliki hasil yang tertunda. Ini membantu dalam jangka panjang karena orang baru perlu mengerjakan kode atau jika kita kembali bekerja pada kode beberapa bulan atau tahun kemudian. Wajar jika kita fokus pada jangka pendek.

Menurut pendapat saya, kemampuan untuk menulis dokumentasi yang baik merupakan salah satu ciri utama yang membedakan programmer hebat dari programmer biasa-biasa saja.

Orang yang paling memenuhi syarat untuk menulis dokumentasi juga orang yang memiliki motivasi paling sedikit untuk melakukannya:

dia adalah:

• terutama pemelihara perpustakaan, bukan pengguna. Jadi semakin kecil dan sederhana perpustakaannya, semakin mudah pekerjaannya. Mempertahankan setengah novel selain kode hanya membuat pekerjaannya lebih sulit,
• dia tahu perpustakaan dalam ke luar, jadi dia tidak perlu dokumentasi,
• dia seorang programmer, dia ingin menulis kode, bukan dokumentasi.

Saya tidak bisa memikirkan siapa pun yang cenderung pergi "Hmm, saya benar-benar harus menghabiskan beberapa jam menulis beberapa dokumentasi yang tepat untuk ini". Kenapa dia?

Dan tentu saja, itu mungkin tidak membantu bahwa ada legenda urban yang beredar di sekitar yang berkomentar ala oksigen yang autogenerasi adalah semua yang Anda butuhkan dalam hal dokumentasi.

Jadi, bahkan dalam kasus yang jarang terjadi di mana pengembang sebenarnya bersedia untuk menulis dokumentasi, itu adalah kesempatan 50/50 bahwa pengembang telah dicuci otak oleh kultus ini untuk berpikir bahwa semua yang diperlukan hanyalah mengisi beberapa komentar seperti itu, memberi tahu Anda permata seperti bahwa "fungsi Foo getFoo()mengembalikan objek bertipe Foo, dan digunakan untuk mendapatkan objek Foo".

Dokumentasi? Kami tidak perlu dokumentasi bau!

Saya tahu bagaimana kode ini bekerja, jadi mengapa saya menghabiskan waktu untuk mendokumentasikan kode saya? Selain itu, saya harus menyelesaikan proyek ini pada hari Jumat dan saya hampir tidak akan berhasil karena ...