Dokumentasi Kode Pertama? [Tutup]

11

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

documentation

— elo
sumber

2

Iya. Itu ide yang bagus. Orang-orang melakukannya sepanjang waktu. Apa lagi yang ingin Anda ketahui?

— S.Lott

9

Ini pertanyaan subyektif. Seseorang telah melakukannya setidaknya beberapa waktu, jadi jawabannya pasti ya. Saya pribadi lebih suka untuk langsung masuk dan membuat prototipe terlebih dahulu, karena saya pasti akan menemukan kembali desain yang lebih baik sekitar 5 kali dalam proses. Saat menangani sesuatu yang kompleks, saya menggores sesuatu di selembar kertas terlebih dahulu. Jika sepele, maka saya cenderung untuk langsung masuk. StyleCop membantu saya untuk mengisi kekosongan di kemudian hari.

— Pekerjaan

2

Itu ide yang bagus, jika tidak, Anda akan memiliki fitur yang tidak berdokumen.

— chrisw

8

@ S.Banyak fakta sederhana bahwa dia menanyakan jenis pertanyaan yang menyiratkan bahwa dia sedang mencari informasi lebih lanjut karena saya cukup yakin Anda sadar. Tapi sepertinya Anda lebih suka berkomentar sinis tentang kesalahan orang lain.

— Kenneth

2

Akan lebih baik jika Anda menulis tes penerimaan, dan kemudian menggunakan TDD untuk memenuhi tes Penerimaan;).

— Martin Blore

5

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.

— Maxpm
sumber

12

Lebih mudah diperbaiki, ya. Lebih mudah diperhatikan, jarang. Desain hampir selalu terlihat bagus sampai Anda mencoba mengimplementasikannya.

— CaffGeek

@Chad Itu benar. Saya telah mengedit jawaban saya untuk mencerminkan hal itu.

— Maks

4

Saya tidak setuju. Membuat dokumentasi lengkap terlebih dahulu jauh lebih buruk daripada hanya cukup dokumentasi untuk mengetahui ke mana harus pergi selanjutnya. Perubahan terjadi. Tidak ada cara untuk mengetahui apakah Anda pergi ke arah yang benar, dan pada saat Anda mengetahuinya, Anda berada jauh di belakang. Pergilah dengan apa yang berhasil, perbaiki dan perbaiki saat Anda pergi, biarkan kodenya menjadi dokumentasi paling mutakhir.

— Zachary Scott

4

Tentu saja segera setelah Anda mengubah kode Anda untuk memperbaiki bug atau untuk memenuhi persyaratan baru, dokumentasi Anda sudah usang. Dokumentasi sebagai tes yang dapat dieksekusi adalah cara yang harus dilakukan!

— Johnsyweb

Buatlah ide (sketsa / garis besar) sebelumnya, tetapi jangan membuat dokumentasi. Kecuali jika Anda lebih suka membuang banyak usaha karena Anda akan membuang banyak usaha awal karena desain dimasukkan ke aplikasi praktis. Plus, hanya kelas / metode publik atau internal yang harus sepenuhnya didokumentasikan (termasuk deskripsi lengkap serta parameter). Barang-barang lokal pribadi harus memiliki satu-baris yang menggambarkan apa yang mereka lakukan untuk referensi di masa depan tetapi hal lain adalah pemborosan karena mereka pasti akan dilewati selama fase pembuatan dokumentasi.

— Evan Plaice

10

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.

— Yuriy Zubarev
sumber

2

+1 untuk TDD. Benar-benar pilihan yang lebih baik daripada mendokumentasikan, maka harus mengubah sejumlah besar dokumentasi jika kode berubah.

— Ethel Evans

Juga memberi +1 untuk dokumentasi dalam bentuk TDD.

— sevenseacat

Anda BISA memiliki dokumentasi produk yang lengkap sebelum produk ada. Saya sudah melakukannya, saya sudah bekerja di proyek-proyek di mana itu merupakan persyaratan. Anda tidak akan memiliki tangkapan layar, tetapi Anda dapat memiliki yang lainnya (termasuk diagram Visio yang mewakili lokasi elemen di layar).

— jwenting

@jwenting saya juga punya dan itu adalah kumpulan diagram serta 200 + halaman dokumen kata. Tidak hanya itu buang-buang waktu, tetapi membutuhkan waktu 2 bulan untuk menghasilkan dan sejumlah besar waktu PM kami untuk terus-menerus memperbarui karena desain berevolusi menjadi produk akhir. Sebenarnya mungkin sudah jauh lebih cepat dengan mockup grafis menggunakan Balsalmiq. Lain kali saya mengerjakan proyek di mana ini adalah persyaratan saya akan membuat titik bahwa orang lain harus ditugaskan untuk mengelolanya penuh waktu karena itulah berapa banyak upaya yang diperlukan untuk mempertahankan.

— Evan Plaice

+1 TDD untuk bukti dasar komponen individu dan diagram untuk asumsi desain keseluruhan (penekanan pada asumsi karena desain yang sebenarnya harus ditulis sebagai aplikasi praktis terbaik bukan sebagai implementasi 1-1 dari diagram, mereka disebut asumsi karena suatu alasan ). Dokumentasi perangkat lunak lengkap untuk semua kelas / metode / properti publik / internal datang terakhir melalui generator dokumentasi (semua properti / pengembalian / komentar harus diisi terlebih dahulu) dan semua barang pribadi / lokal mendapat satu baris untuk menggambarkan apa yang mereka lakukan untuk referensi di masa mendatang (pribadi / lokal diabaikan oleh generator).

— Evan Plaice

7

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.

Persis! Perubahan terjadi. Dokumentasi membusuk. Kode adalah bentuk dokumentasi yang paling benar.

— Zachary Scott

3

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.

— Kenneth
sumber

3

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.

— DPM
sumber

Ini adalah saran yang bagus, tetapi dokumentasi yang baik termasuk penggunaan API.

— Frank Hileman

Sebagai catatan, sementara saya menghargai suntingan, saya pikir kutipan itu mungkin bukan yang saya pikirkan. Tampaknya terkait secara tangensial dan lebih tinggi atau terkait dengan fase persyaratan. Saya pikir dia mengatakan bahwa sebelum menulis dokumentasi dia akan mulai coding, menulis kode klien yang akan menggunakan antarmuka untuk memiliki gambaran kasar tentang antarmuka yang tepat dan bahwa (ini adalah bagian kontra intuitif menurut saya) yang harus didahulukan, sebelum menulis dokumen desain tingkat rendah sama sekali. Tentu saja ini salah saya karena tidak menemukan kutipan ketika saya menulis jawaban ini.

— DPM

1

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

Tulis siaran persnya
Tulis sebuah FAQ
Tentukan pengalaman pelanggan
Tulis Manual Pengguna
Mulai pemrograman

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

— asmaier
sumber

1

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:

Deskripsi : "nada penjualan" pendek. Beri tahu pembaca mengapa mereka harus terus membaca.
Contoh cepat : cuplikan kode pendek atau tangkapan layar untuk mendukung deskripsi.
Mulai cepat : cara memulai , menginstal instruksi, dan lebih banyak contoh.
Dokumentasi lebih lanjut : tautan ke dokumen lengkap dan info lebih lanjut.
Organisasi proyek : siapa penulisnya, cara berkontribusi, cara mengajukan bug.
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:

— Yevgeniy Brikman
sumber

0

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.

— Celup
sumber

0

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.

— SnoopDougieDoug
sumber