Berapa banyak dokumentasi yang cukup?

Berapa banyak dokumentasi teknis (untuk pengembang masa depan) yang cukup ? Apakah ada rasio antara pengkodean jam dan dokumentasi yang tepat?

Papadimoulis berpendapat bahwa Anda harus

menghasilkan paling sedikit dokumentasi yang dibutuhkan untuk memfasilitasi sebagian besar pemahaman,

Apakah itu pedoman yang baik, atau adakah hal-hal spesifik yang harus saya buat?

Bagaimana dengan beberapa pengujian kegunaan lorong? Tampilkan kode dan dokumentasi untuk pengembang yang tidak terbiasa dengan proyek. Ketika Anda bisa melakukan itu tanpa dorongan besar untuk menjelaskan sesuatu sambil menonton mereka meninjau kode, Anda sudah cukup.

Dengan demikian, Anda tidak akan mendapatkan masalah ini selain biaya tambahan, tetapi juga biaya tambahan untuk pensiunan.
Antoine de Saint-Exupéry

Saya sudah memikirkan topik ini untuk sementara waktu.

Kesimpulan saya adalah - ini bukan masalah kuantitas, tetapi kualitas dan konteks.

Misalnya, struktur proyek yang tepat mengalahkan komentar yang menjelaskan di mana file berada (implementasi vs intensi)

Demikian pula, klasifikasi untuk memperjelas konteks mengalahkan penamaan (Id on a Patient -> Patient.Id).

Saya percaya DDD memiliki suara dalam dokumentasi yang baik - klasifikasi menyediakan konteks, konteks menciptakan batas dan batas mengarah ke implementasi yang disengaja (ini adalah tempat ini berada, daripada perlu ada).

Kode itu sendiri tidak cukup baik untuk dianggap sebagai dokumentasi. Masalah dalam kebanyakan kasus tidak terletak pada kenyataan bahwa kerja kode dikomentari atau tidak dikomentari, melainkan kekuatan pendorong (logika domain) tidak.

Kita kadang-kadang lupa siapa bosnya - jika kode berubah, logika domain atau nalar tidak boleh, tetapi jika logika atau alasan domain mengubah kode pasti akan.

Konsistensi juga sangat penting - konvensi itu sendiri tidak berguna jika tidak konsisten.

Pola desain bukan hanya 'praktik yang baik' - tetapi juga harus dipahami oleh para pengembang. Memberitahu pengembang untuk menambahkan jenis baru ke Pabrik lebih dipahami daripada menambahkan jenis baru ke metode (di mana konteks dan konsistensi lemah atau hilang).

Setengah perjuangan adalah keakraban .

Di samping catatan, API yang tampaknya mendukung banyak dokumentasi juga sangat sensitif terhadap domain dan konteks. Kadang-kadang fungsi duplikasi tidak jahat (hal yang sama, konteks yang berbeda) dan harus diperlakukan sebagai terpisah.

Dalam hal berkomentar, selalu baik untuk menunjukkan logika domain di balik alasan tersebut.

Misalnya, Anda bekerja di industri medis. Dalam metode Anda, Anda menulis "IsPatientSecure = true;"

Sekarang, setiap programmer yang baik dapat mengetahui bahwa pasien sedang ditandai sebagai aman. Tapi kenapa? Apa implikasinya?

Dalam hal ini pasien adalah narapidana yang dipindahkan dengan aman ke rumah sakit di luar gedung. Mengetahui hal ini, lebih mudah untuk membayangkan peristiwa yang mengarah ke titik ini (dan mungkin apa yang masih perlu terjadi).

Mungkin posting ini tampaknya filosofis terbaik - tetapi ingat bahwa ini adalah 'alasan' atau 'logika' yang Anda tulis - bukan kode.

Saya setuju dengan kutipan Papadimouslis. Kode sumber dapat berbicara untuk dirinya sendiri, tetapi kode tidak dapat memberi tahu Anda mengapa ada, bagaimana harus digunakan, dan bagaimana kode tersebut harus berperilaku.

Saya tidak tahu rasio yang baik.

Saya mewarisi ratusan baris kode dengan sedikit dokumentasi. Menjadi sulit bagi saya untuk memahami mengapa kode itu ditulis. Setelah saya mengetahui mengapa kode itu ditulis, saya harus mencari cara untuk menggunakan kode tersebut. Setelah saya mengetahui hal itu, saya harus mengerti bagaimana seharusnya berperilaku sehingga saya dapat mendukung dan memelihara kode.

Hanya dari pengalaman, jangan membuat komentar terlalu spesifik atau Anda akhirnya harus mempertahankan kode aktual dan dokumentasi. Ini adalah mimpi buruk ketika dokumentasi dan kode tidak sinkron.

Cukup membuat Anda berhenti menebak-nebak diri sendiri.

Jika sewaktu-waktu selama Anda bekerja Anda seperti "hmm mungkin saya harus mendokumentasikan ini", silakan dan lakukan. Kemudian, jika Anda telah menulis beberapa dokumentasi dan Anda seperti "mungkin saya harus menjelaskan ini lebih lanjut", silakan dan lakukan itu.

Bilas-ulangi sampai perasaan itu hilang.

Saya telah menemukan bahwa pendekatan berbasis risiko seperti yang disajikan dalam buku Just Fair Fairs Arsitektur George Fairbanks bekerja sangat baik untuk memahami seberapa banyak dokumentasi yang cukup. Anda dapat membaca bagian yang menyajikan konsep ini (bab 3) di situs webnya tetapi gagasan utamanya adalah untuk:

• Ekspresikan hal-hal yang membuat Anda khawatir tentang "pemahaman sistem" sebagai risiko
• Prioritaskan risiko
• Mitigasi risiko sampai tim Anda merasa risiko proyek telah cukup berkurang. Dalam hal ini Anda mungkin akan membuat semacam dokumentasi.

Untuk membantu mengkalibrasi masalah sehingga Anda dapat memprioritaskan risiko, saya merasa sangat membantu untuk mengidentifikasi beberapa tujuan yang dikenal sebagai Ambang Batas Keberhasilan , yaitu sekumpulan tujuan minimum yang menurut tim Anda harus dicapai oleh proyek "sukses". Dari perspektif dokumentasi, contoh ToS mungkin kira-kira seperti "Pengembang harus dapat membangun plug-in sederhana dalam waktu 4 jam setelah mengambil kerangka kerja untuk pertama kalinya."

Sekarang identifikasi beberapa risiko. Dengan sistem yang Anda bangun (atau sedang membangun) hal-hal apa yang paling mengkhawatirkan tim Anda? Ungkapkan ini sebagai pernyataan risiko. Saya suka gaya konsekuensi-kondisi SEI tetapi ada yang lain. Contoh:

• Model data besar dan kompleks; pengembang mungkin tidak tahu elemen data mana yang digunakan dalam situasi tertentu.
• Sistem memiliki batas koneksi API untuk meningkatkan keandalan; pengembang mungkin secara tidak sengaja melampaui batas koneksi.
• Pengaya dikonsumsi dalam beberapa langkah berurutan; pengembang mungkin tidak membangun plug-in dengan mempertimbangkan langkah-langkah yang diperintahkan ini.

Sekarang sebagai tim, prioritaskan risikonya. Multi-voting bekerja sangat baik.

Mitigasi risiko prioritas utama, dan ulangi mulai dengan identifikasi sampai risiko proyek Anda gagal (didefinisikan oleh Ambang Batas Keberhasilan) berada dalam batas yang dapat ditoleransi. Secara umum ini berarti Anda akan memiliki beberapa risiko yang disetujui tim tidak terlalu menjadi perhatian. Ingatlah bahwa Anda mungkin tidak ingin mengurangi semua risiko. Contoh strategi mitigasi untuk risiko terakhir di atas mungkin dengan membuat tutorial.

Sesedikit mungkin, tetapi sebanyak yang diperlukan

Saya tidak ingat di mana & kapan saya pertama kali mendengarnya, tetapi ini adalah pepatah dengan banyak aplikasi.

Semakin kompleks teknologi atau aplikasinya, semakin banyak dokumentasi yang dibutuhkan (jelas), tetapi jelas Anda tidak ingin membuang waktu dengan berlebihan.

'Tes lorong' JohnFx adalah suara. Tapi percayalah pada diri sendiri; Anda mengembangkan kode, dan Anda semua orang harus memiliki rasa untuk elemen yang membutuhkan perhatian ekstra, dan elemen yang akan jelas bagi semua. Pikirkan perjuangan Anda mengembangkan kode dan Anda mungkin akan memiliki gagasan apa yang pengembang lain akan melihat ketika mereka melihat kode Anda.

Lupakan hubungan apa pun antara upaya yang dihabiskan dengan pengkodean dan upaya yang dihabiskan untuk mendokumentasikan.

Saya percaya Anda tidak bisa memasukkan ini ke dalam aturan yang tepat. Alasan untuk mendokumentasikan adalah untuk memberikan pengetahuan yang tidak mudah dikumpulkan dari kode mentah dalam bentuk sehingga orang lain dapat mengerti dan bahkan mungkin memelihara kode mentah tersebut.

Oleh karena itu satu-satunya cara Anda dapat mengetahui apakah Anda telah cukup mendokumentasikan, adalah bertanya kepada audiens target apakah itu cukup baik. Saya percaya proses "peer review" sangat baik dalam melakukan ini di muka. Perhatikan berapa banyak penjelasan yang diperlukan untuk membuat teman Anda memahami apa yang Anda bicarakan, dan bekerja untuk meminimalkannya.

Jika Anda belum pernah melakukan ini sebelumnya, Anda tidak dapat memperkirakan berapa banyak pekerjaan yang akan dilakukan, tetapi setelah beberapa iterasi Anda akan mendapatkan ide yang lebih baik tentang berapa banyak yang dibutuhkan.