Dokumentasi Kode Pertama? [Tutup]

Adakah yang pernah mencoba membuat dokumentasi kode lengkap terlebih dahulu, sebelum benar-benar menulis kode? Saya memikirkan hal ini sebelumnya karena saya pikir akan membantu untuk menulis antarmuka konkret dan memastikan desain awal Anda tidak didasarkan dengan membuat Anda berpikir tentang bagaimana kelas berinteraksi. Apakah ini ide yang bagus? Adakah yang sudah mencobanya? Elo

Iya.

Ini membuat Anda berpikir tentang apa, tepatnya, kode Anda yang seharusnya dilakukan. Idenya adalah Anda bisa mulai dengan bagian mana pun dari kode dan tahu persis apa yang perlu dilakukan untuk menyelesaikan modul itu.

Ini juga lebih mudah memperbaiki sesuatu di papan gambar daripada di IDE.

Ada dua cara untuk memikirkannya:

1) Dokumentasi seperti pada dokumen Word, Wiki, dll. Menurut definisi Anda tidak dapat memiliki dokumentasi kode lengkap karena Anda tidak memiliki kode untuk didokumentasikan. Anda dapat mencoba mendokumentasikan desain, asumsi, antarmuka, dan kontrak tingkat tinggi terlebih dahulu.

2) Dokumentasi sebagai tes yang dapat dieksekusi. Ada aliran pemikiran yang menyatakan bahwa tes unit yang dapat dieksekusi adalah dokumentasi terbaik. Sekolah pemikiran ini juga menganjurkan dokumentasi semacam ini sebelum menulis kode (TDD). Pada saat yang sama Anda tidak menulis semua tes untuk seluruh sistem sejak awal. Anda memecahnya dengan menggunakan kasus pertama, lalu Anda melakukan tes dan kode per kasus penggunaan.

Dimulai dengan dokumentasi model air terjun klasik, dan memiliki semua perangkap yang terkait dengan model itu. Secara umum, semakin Anda mendokumentasikan semakin Anda harus memperbarui ketika persyaratan berubah. Salah satu manfaat memulai dengan dokumentasi pengguna adalah bahwa Anda mungkin mendapatkan umpan balik (dan karenanya berubah) lebih cepat. Tetapi pengalaman menunjukkan bahwa kebanyakan orang buruk dalam memetakan dokumentasi mental untuk tindakan. Jadi kami menggunakan prototipe sebagai gantinya, yang memungkinkan orang untuk benar-benar menggunakan perangkat lunak dan memberikan umpan balik seperti itu.

Salah satu variasi pada "dokumentasi pertama" adalah pemrograman melek . Mulailah dengan menulis deskripsi tentang apa yang akan dilakukan program dari perspektif pemrogram. Terus atur itu sampai kompilasi. Voila, program melek huruf.

Saya pribadi merasa lebih baik menggunakan diagram (seperti UML) untuk melakukan pemodelan sederhana untuk menunjukkan aliran sesuatu. Ini jauh lebih cepat daripada mendokumentasikan hal-hal dalam kata-kata dan jika dilakukan dengan benar bisa sama deskriptif. Saya akan ragu-ragu untuk melakukan Dokumentasi Lengkap meskipun karena secara pribadi saya belum pernah memiliki proyek yang saya kerjakan yang tidak berubah selama kursus pemrograman itu.

EDIT: Beberapa dokumentasi harus dilakukan sambil jalan. Ini membuatnya lebih mudah untuk melakukan dokumentasi lengkap nanti.

Joshua Bloch membahas hal ini dalam wawancaranya untuk buku "Coders at Work".

Bertentangan dengan pandangan yang lebih ortodoks dan akademis, ia menyarankan sesuatu untuk menyelaraskan pikiran Anda (mungkin Anda sudah membacanya di sana sendiri?): Bahwa sebelum menulis dokumentasi Anda harus memahami apa yang Anda inginkan dari sistem dan mendapatkan yang lebih "nyata". "perasaan. Untuk tujuan ini ia akan merancang bagian dari antarmuka dan beberapa kode klien yang menggunakannya.

Yang paling penting adalah mengetahui apa yang Anda coba bangun: masalah apa yang ingin Anda selesaikan. Pentingnya analisis persyaratan tidak dapat dilebih-lebihkan. Ada orang yang berpikir, “Oh, ya, analisis persyaratan; Anda pergi ke pelanggan Anda, Anda berkata, 'Apa yang Anda butuhkan?' Dia memberi tahu Anda, dan Anda selesai. "

Tidak ada yang bisa lebih jauh dari kebenaran. Tidak hanya negosiasi tetapi juga proses pemahaman. Banyak pelanggan tidak akan memberi tahu Anda masalah; mereka akan memberi tahu Anda solusinya. Seorang pelanggan mungkin berkata, misalnya, “Saya ingin Anda menambahkan dukungan untuk 17 atribut berikut ke sistem ini. Maka Anda harus bertanya, 'Kenapa? Apa yang akan Anda lakukan dengan sistem? Bagaimana Anda mengharapkannya berkembang? '”Dan seterusnya. Anda bolak-balik sampai Anda tahu apa yang benar-benar dibutuhkan oleh pelanggan untuk perangkat lunak. Ini adalah kasus penggunaan.

Menghadirkan satu set kasus penggunaan yang baik adalah hal terpenting yang dapat Anda lakukan pada tahap ini. Setelah memilikinya, Anda memiliki tolok ukur yang dapat digunakan untuk mengukur solusi yang memungkinkan. Tidak apa-apa jika Anda menghabiskan banyak waktu untuk membuatnya cukup dekat dengan benar, karena jika Anda salah, Anda sudah mati. Sisa proses akan menjadi latihan sia-sia.

Hal terburuk yang dapat Anda lakukan — dan saya telah melihat ini terjadi — adalah Anda membawa sekelompok orang pintar ke ruangan untuk bekerja selama enam bulan dan menulis spesifikasi sistem 247 halaman sebelum mereka benar-benar memahami apa itu sebenarnya mereka mencoba membangun. Karena setelah enam bulan, mereka akan memiliki sistem yang ditentukan dengan sangat tepat yang mungkin tidak berguna. Dan sering kali mereka berkata, "Kami telah berinvestasi begitu banyak dalam spesifikasi sehingga kami harus membangunnya." Jadi mereka membangun sistem yang tidak berguna dan tidak pernah digunakan. Dan itu mengerikan. Jika Anda tidak memiliki kasing bekas, Anda membangunnya dan kemudian mencoba melakukan sesuatu yang sangat sederhana dan Anda menyadari bahwa, “Ya ampun, melakukan sesuatu yang sangat sederhana seperti mengambil dokumen XML dan mencetaknya membutuhkan halaman demi halaman boilerplate kode." Dan itu hal yang mengerikan.

- Joshua Bloch, dari wawancara dalam " Coders at Work: Reflections on the Craft of Programming " oleh Peter Seibel

Jika Anda sudah berpikir seperti ini, akan baik jika Anda bisa mendapatkan buku itu dan membaca seluruh wawancara. Seperti yang saya katakan, dia selalu sangat mencerahkan.

Beberapa orang bahkan melangkah lebih jauh dan menyatakan bahwa perusahaan harus benar-benar bekerja mundur, jadi

1. Tulis siaran persnya
2. Tulis sebuah FAQ
3. Tentukan pengalaman pelanggan
4. Tulis Manual Pengguna
5. Mulai pemrograman

Lihat http://www.allthingsdistributed.com/2006/11/working_backwards.html

Menulis dokumentasi kode lengkap terlebih dahulu mungkin berlebihan dan agak mengingatkan pada metodologi air terjun. Namun, saya telah menemukan bahwa pendekatan yang lebih pragmatis adalah menulis README terlebih dahulu. Inilah alasannya:

README tidak mendokumentasikan setiap detail proyek Anda. Sebaliknya, biasanya berisi info berikut:

1. Deskripsi : "nada penjualan" pendek. Beri tahu pembaca mengapa mereka harus terus membaca.
2. Contoh cepat : cuplikan kode pendek atau tangkapan layar untuk mendukung deskripsi.
3. Mulai cepat : cara memulai , menginstal instruksi, dan lebih banyak contoh.
4. Dokumentasi lebih lanjut : tautan ke dokumen lengkap dan info lebih lanjut.
5. Organisasi proyek : siapa penulisnya, cara berkontribusi, cara mengajukan bug.
6. Pemberitahuan hukum : lisensi, hak cipta, dan detail hukum lainnya.

Menulis "promosi dagang" di depan memaksa saya untuk menjadi sangat jelas tentang mengapa proyek ini harus ada dan mengapa pengembang harus menggunakannya. Tindakan menulis kalimat penuh hanya untuk menggambarkan proyek sering mengubahnya menjadi lebih baik: Anda memahaminya lebih baik, mengembangkan ide-ide baru, dan mengungkap potensi masalah. Ini juga alat prioritas yang bagus: apa pun di "promosi dagang" adalah yang harus dimiliki!

"Contoh cepat" dan "panduan mulai cepat" memaksa saya untuk memikirkan kasus penggunaan utama dari perspektif pengguna. Saya telah menemukan bahwa melakukan ini sebelum menulis kode apa pun - sebelum macet dalam detail implementasi dan tenggat waktu yang ketat - mengarah ke API dan desain yang jauh lebih bersih. Ingat: program harus ditulis untuk dibaca orang, dan hanya untuk mesin yang dieksekusi ( SICP ).

Dalam "dokumentasi lebih lanjut", saya membuat garis besar potongan-potongan yang akan membutuhkan dokumentasi terperinci, untuk dilakukan nanti. "Organisasi proyek" memungkinkan saya mencari tahu siapa yang akan mengerjakan proyek dan praktik pengkodean. "Pemberitahuan hukum" ... yah, bisa juga membuat mereka keluar dari jalan juga.

Setelah Anda memiliki README dasar ini, Anda memiliki dokumen yang berguna untuk diskusi, ulasan desain, membagi pekerjaan, dan perencanaan proyek. Saat Anda mengerjakan proyek, sering-seringlah periksa kembali dengan README untuk memastikan Anda masih di jalurnya. Selain itu, secara bertahap memperbarui README dan "dokumentasi lebih lanjut" saat Anda selesai berarti semua dokumentasi Anda akan dilakukan ketika kode selesai, yang merupakan pengalaman yang jauh lebih menyenangkan daripada harus terburu-buru mendokumentasikan semuanya pada menit terakhir.

Untuk info lebih lanjut, lihat hal berikut:

1. Pengembangan Berbasis Readme
2. Kode yang paling penting bukanlah kode
3. Anda adalah apa yang Anda dokumentasikan

Mengapa Anda tidak ingin memikirkan bagaimana kelas berinteraksi? Mengapa itu hal yang buruk? Saya benar-benar memikirkan interaksi sebelum saya tahu apa kelasnya. Dengan cara itu kelas mengidentifikasi diri mereka sendiri.

Anda harus memiliki beberapa gagasan tentang apa yang Anda rencanakan untuk dilakukan sebelum Anda menulis kode. Masalahnya selalu adalah bagaimana Anda menyimpan apa yang telah Anda kodekan dengan apa yang Anda tulis? Ada yang bilang jangan mencoba, ada yang bilang lupakan dokumen awal dan pertahankan komentarnya. Tentu saja kode selalu menjadi sumber kanonik. Masalahnya kemudian menjadi apakah layak untuk mendokumentasikan apa yang dilakukan kode untuk mereka yang datang kemudian atau menggunakan kode. Siapa pun dapat mengetahui apa fungsi suatu fungsi. Tugas penulis adalah membantu seseorang memahami dalam 5 menit apa yang dapat diketahui siapa pun dalam satu jam. Tambahkan delta dan tentukan jalur Anda.