Haruskah Anda mendokumentasikan semuanya atau hanya sebagian besar?

Tampaknya sedikit subjek yang kontroversial untuk mendokumentasikan segala sesuatu, termasuk sintaks "JavaBean" getter dan setter untuk bidang: Orang - orang mengatakan bahwa KERING panjang dan berulang-ulang yang tidak perlu (jangan ulangi sendiri) , bahwa konvensi penamaan harus menjelaskan semuanya , dan itu mengacaukan kode / dokumentasi. Terkadang argumen itu berhasil. Tetapi di lain waktu, Anda berakhir dengan ini:

Di atas adalah umum untuk proyek sumber terbuka yang benar-benar mengikuti prinsip-prinsip tersebut. Anda memiliki dokumentasi yang sama sekali tidak berguna . Itu tidak menjelaskan apa-apa tentang apa yang terjadi di bawahnya, efek yang mungkin, atau bahkan apa nilai yang diharapkan (mungkinkah itu nol atau tidak pernah nol? Saya tidak tahu; Javadoc tidak memberi tahu saya).

Jadi kapan saya harus mendokumentasikan? Apakah saya mendokumentasikan semuanya meskipun kadang-kadang kode berantakan? Atau apakah saya tidak mendokumentasikan apa pun karena menurut saya "jelas"?

Dokumentasikan semua yang masuk akal untuk didokumentasikan .

Di dunia yang ideal, ya, Anda akan mendokumentasikan semuanya. Namun, di Bumi, kami memiliki tenggat waktu, pemotongan fitur, keluarga dan teman untuk dikunjungi, liburan yang harus diambil, hanya 24 jam dalam sehari dan hanya 365 hari dalam setahun. Tidak cukup waktu untuk mendokumentasikan semuanya. Jadi, secara optimal, dokumentasikan semua yang Anda bisa (Anda tidak akan selesai), tetapi dapatkan hasil maksimal dari uang Anda dengan:

• Buat kode dapat dibaca dan tanda tangan metode sejelas mungkin sehingga mendokumentasikan kurang mungkin diperlukan.
• Mendokumentasikan hal-hal yang paling tidak jelas terlebih dahulu. Bantu orang lain dengan mendokumentasikan peretasan gila yang harus Anda lakukan untuk menyelesaikan masalah.
• Dokumentasikan mengapa sebelum apa - Jangan berkomentar apa yang dilakukan sesuatu, seperti "Iterate atas catatan pelanggan di mana saldo kurang dari nol dan peringkat kurang dari satu dan menambahkannya ke daftar Pelanggan bebas biaya". Dokumentasikan mengapa Anda menambahkannya ke daftar dalam bahasa Inggris (atau bahasa tim Anda), seperti "Karena pelanggan ini memiliki saldo negatif dan peringkat rendah, mereka menyebabkan kami kehilangan uang, jadi kecualikan mereka karena tidak bisa check out.

Teruslah mendokumentasikan hingga Anda dapat melihat orang lain membacanya tanpa merasa perlu menjelaskan apa pun.

Minggu terakhir ini ada artikel bagus tentang dokumentasi di The Daily WTF. Saya pikir itu mengatakan segalanya, jadi saya akan meninggalkan tautan:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Pada dasarnya dikatakan bahwa Anda tidak boleh mendokumentasikan sesuatu jika itu tidak akan berguna (beberapa dokumentasi dibiarkan membusuk di laci) dan mendokumentasikan sedikitnya informasi yang diperlukan untuk memahami bagian tertentu dari proyek. Terlalu banyak dokumentasi hanya membingungkan pembaca.

Sangat tergantung pada seberapa mudah dibaca kode tersebut bagi audiens yang membacanya. Cari tahu siapa audiens untuk membaca kode Anda, dan mintalah seseorang yang memenuhi profil itu membaca kode Anda.

Pendekatan lain adalah meninjau kode Anda sendiri setelah seminggu dan melihat apakah Anda masih mengerti apa yang Anda lakukan, jika tidak, dokumentasikan dan tinjau kode dalam dua minggu atau lebih.

Sementara saya menghargai dokumentasi yang jelas dan luas, tidak ada yang seperti kode mendokumentasikan diri. Jadi, intinya (bagi saya) adalah:

Sangat curiga terhadap dokumentasi (kode sumber); mencoba dan membuatnya berlebihan dengan meningkatkan kode, tetapi jangan menghindar dari mendokumentasikan dengan jelas dan sepenuhnya ketika diperlukan.

Tentu saja, dalam keadaan tertentu, dokumentasi mungkin diperlukan untuk alasan selain 'menjelaskan apa yang dilakukan kode' (misalnya: basis tim besar, standar organisasi, dan sebagainya).

Saran saya pada dokumentasi adalah bahwa jika ada sesuatu yang mewah dalam kode, itu termasuk dalam dokumen yang harus selalu diperbarui. Senang menjadi subjek banyak interpretasi, dalam pikiran saya adalah di mana sesuatu dilakukan dengan cara tertentu yang mungkin memiliki efek samping yang harus dicatat, misalnya sesuatu dapat dilakukan secara rekursif untuk memastikan bahwa barang cucu diproses melalui pohon simpul untuk melakukan beberapa tes pada semua keturunan. Mengartikulasikan mengapa sesuatu dilakukan dengan cara tertentu dapat menjadi cara yang baik untuk mengetahui apakah ada alasan yang baik untuk menggunakan sesuatu.

Secara sederhana, dokumentasi ada untuk membantu pengembang sekarang, dan pengelola di masa depan.

Jika Anda ingat pepatah sederhana itu, maka tingkat dokumentasi harus ditentukan sendiri.

Dokumentasi, demi dokumentasi, adalah buang-buang waktu ... tetapi menjelaskan hari ini apa yang Anda lakukan lebih bermanfaat daripada seseorang yang harus merekayasa ulang kode Anda dalam waktu lima tahun.

Secara pribadi saya pergi dengan pendekatan mempertimbangkan mendokumentasikan segalanya. Yaitu saat coding saya mempertimbangkan pada setiap titik apakah dokumentasi akan menambah nilai. Sebagian besar waktu jawabannya adalah ya untuk jenis kendala dan pengetahuan domain yang disebutkan dalam pertanyaan awal. Misalnya, kemampuan nol, batasan unik, interpretasi bidang dalam domain yang lebih luas.

Untuk menghindari duplikasi, saya cenderung mendokumentasikan kelas API utama dengan informasi seperti ini. Maka hanya mendokumentasikan implementasi dan internal di mana ada perilaku yang tidak jelas atau tidak konsisten. Saya menemukan ini berfungsi dengan baik karena para pengguna API yang paling membutuhkan bantuan dan dokumentasi, umumnya aman untuk menganggap orang-orang yang memodifikasi implementasi tahu API sehingga memiliki pengetahuan ini.

Saya juga cenderung mendokumentasikan getter saja. Saya tidak menduplikasi dokumentasi ke setter, definisi bidang dan parameter konstruktor. Saya hanya mendokumentasikan perilaku yang tidak jelas seperti default di tempat-tempat ini. Perilaku apa pun yang dapat disimpulkan dari dokumentasi pengambil tidak didokumentasikan. Misalnya, jika pengambil didokumentasikan sebagai null yang tidak pernah kembali, saya biasanya tidak mendokumentasikan bahwa Anda tidak dapat meneruskan null ke penyetel, kecuali ada default.

Beberapa orang suka menandai tindakan "mempertimbangkan dokumentasi" ini dengan menambahkan komentar kosong di mana mereka telah mempertimbangkan dokumentasi tetapi merasa tidak perlu. Saya tidak suka praktik ini karena hanya mengacaukan kode dan menghalangi.