Pemaju Kenapa Anda Tidak Perlu Langkau Dokumentasi

Dalam bidang pembangunan aplikasi mudah alih, aplikasi web, aplikasi desktop, atau perpustakaan JavaScript, dokumentasi memainkan peranan penting yang dapat menentukan kejayaan pembangunan perisian. Tetapi jika anda pernah melakukan dokumentasi, anda akan bersetuju dengan saya bahawa ia adalah perkara paling kurang yang paling kegemaran untuk pemaju lakukan.

Tidak seperti kod bertulis (yang merupakan pemaju yang ditandatangani untuk melakukan), dokumentasi (yang tidak kita lakukan) harus dan harus dicerna dengan mudah oleh semua orang. Secara teknikalnya, kita perlu menterjemahkan bahasa mesin (kod) ke dalam bahasa yang dapat difahami oleh manusia, yang lebih sukar daripada bunyi.

Walaupun ia boleh menjadi beban yang berat, menulis dokumentasi adalah penting dan akan memberikan kelebihan untuk pengguna anda, rakan sekerja anda, dan terutama diri anda sendiri.

Dokumentasi Baik Membantu Pengguna

Dokumentasi membantu pembaca faham bagaimana kod berfungsi, jelas. Tetapi ramai pemaju membuat kesilapan dengan mengandaikan bahawa pengguna perisian akan mahir. Oleh itu, dokumentasi mungkin menjadi bahan nipis, melangkaui banyak keperluan yang harusnya terkandung dari awal. Jika anda pandai dalam bahasa, anda boleh memikirkan perkara-perkara dalam inisiatif anda sendiri; jika anda tidak, maka anda akan hilang.

Dokumentasi yang dimaksudkan untuk pengguna biasanya terdiri daripada penggunaan praktikal atau “bagaimana untuk”. Peraturan praktikal apabila membuat dokumentasi untuk pengguna am ialah ia harus jelas. Menggunakan kata mesra manusia lebih baik dari istilah teknikal atau jargon. Contoh penggunaan sebenar juga akan sangat dihargai.

Reka bentuk susun atur yang baik juga akan membantu mengimbas pengguna melalui setiap bahagian dokumentasi tanpa tekanan mata. Beberapa contoh yang baik (aka kegemaran saya) adalah dokumentasi untuk Bootstrap dan WordPress ' “Langkah Pertama Dengan WordPress”.

Ia Membantu Pemaju Lain Terlalu

Setiap pemaju akan mempunyai gaya pengkodan mereka sendiri. Tetapi, apabila bekerja dalam pasukan, kami sering perlu berkongsi kod dengan rakan pasukan lain. Oleh itu, adalah penting untuk mempunyai persetujuan mengenai standard untuk memastikan semua orang berada pada halaman yang sama. Dokumentasi bertulis yang betul akan menjadi rujukan keperluan pasukan

Tetapi tidak seperti dokumentasi pengguna akhir, dokumentasi ini biasanya menerangkan prosedur teknikal seperti konvensyen penamaan kod, menunjukkan bagaimana halaman tertentu hendak dibina, dan bagaimana API berfungsi bersama dengan contoh kod. Selalunya kita juga perlu menulis dokumentasi selaras dengan kod (dikenali sebagai komen) untuk menerangkan apa yang dilakukan oleh kod.

Di samping itu, dalam kes di mana anda ada ahli baru menyertai pasukan anda kemudian, dokumentasi ini boleh menjadi cara yang berkesan masa untuk melatih mereka, jadi anda tidak perlu memberi mereka lari 1-on-1 pada kod.

Anehnya Ia Juga Membantu Coder

Perkara yang lucu tentang pengekodan kadang kala bahkan pemaju sendiri tidak memahami kod yang mereka tulis. Ini adalah benar terutamanya dalam kes-kes di mana kod-kod telah tidak disentuh selama berbulan-bulan atau bahkan tahun.

Satu keperluan tiba-tiba untuk mengkaji semula kod untuk satu sebab atau yang lain akan meninggalkan seseorang yang tertanya-tanya apa yang berlaku di fikiran mereka ketika mereka menulis kod-kod ini. Jangan terkejut: Saya berada dalam situasi ini sebelum ini. Ini adalah tepatnya bila saya berharap Saya telah didokumenkan kod saya dengan betul.

Dengan mendokumenkan kod anda, anda akan dapat sampai ke bahagian bawah kod anda dengan cepat dan tanpa kekecewaan, menjimatkan banyak masa anda yang boleh dibelanjakan untuk mendapatkan perubahan dalam.

Apa yang Membuat Dokumentasi Baik?

Terdapat beberapa faktor yang membina dokumentasi yang baik.

1. Jangan Assume

Jangan menganggap bahawa pengguna anda tahu apa anda tahu serta apa mereka ingin tahu. Ia sentiasa lebih baik untuk bermula dari awal lagi tanpa mengira tahap kecekapan pengguna.

Jika anda membina plugin jQuery, sebagai contoh, anda mungkin mengambil inspirasi daripada dokumentasi SlickJS. Ia menunjukkan bagaimana untuk menyusun HTML, di mana untuk meletakkan CSS dan JavaScript, bagaimana untuk memulakan plugin jQuery pada tahap yang paling asas, dan juga menunjukkan markup terakhir yang lengkap selepas menambah semua barangan ini, yang mana sesuatu yang jelas.

Intinya adalah dokumentasi ditulis dengan proses pemikiran pengguna, bukan pemaju. Mendekati dokumentasi anda sendiri dengan cara ini akan memberikan anda perspektif yang lebih baik dalam mengatur sekeping anda sendiri.

2. Ikuti Standard

Dalam menambah dokumentasi yang selaras dengan kod, gunakan piawaian yang diharapkan dari bahasa tersebut. Ia sentiasa merupakan idea yang baik untuk menggambarkan setiap fungsi, pembolehubah, dan juga nilai yang dikembalikan oleh fungsi. Berikut adalah contoh dokumentasi inline yang baik untuk PHP.

 / ** * Menambah kelas tersuai ke pelbagai kelas badan. * * @ array array $ kelas Kelas untuk elemen badan. * @return array * / function body_classes (kelas $) // Menambah kelas blog kumpulan ke blog dengan lebih dari 1 penulis yang diterbitkan. jika (is_multi_author ()) $ classes [] = 'kumpulan-blog';  kelas $ kembali;  add_filter ('body_class', 'body_classes'); 

Berikut adalah beberapa rujukan untuk memformat dokumentasi sebaris dengan amalan terbaik dalam PHP, JavaScript dan CSS:

• PHP: Standard Dokumentasi PHP untuk WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Sekiranya anda menggunakan SublimeText saya cadangkan untuk memasang DocBlockr yang akan memaklumkan terlebih dahulu kod anda dengan dokumentasi sebaris.

3. Unsur-unsur grafik

Gunakan unsur grafik, mereka bercakap lebih baik daripada teks. Media ini berguna, terutamanya jika anda membina perisian dengan antara muka grafik. Anda boleh menambah unsur penunjuk seperti anak panah, bulatan, atau apa-apa yang boleh membantu pengguna untuk mengetahui di mana hendak pergi untuk mencapai langkah-langkah, tanpa meneka.

Berikut adalah contoh dari aplikasi Menara di mana anda boleh menarik inspirasi dari. Mereka secara efisien menjelaskan bagaimana cara kerja kawalan versi dalam cara yang menyenangkan yang menjadikannya lebih mudah difahami daripada menggunakan baris arahan teks biasa.

4. Seksyen

Anda boleh mempertimbangkan untuk membungkus beberapa perkara dalam dokumentasi dalam senarai dan jadual yang dibolot kerana ini menjadikan kandungan lebih mudah untuk mengimbas dan membaca untuk pengguna.

Menambah jadual kandungan dan memecah dokumentasi dalam bahagian yang mudah dicerna, namun menjaga setiap bahagian relevan dengan apa yang akan datang. Pastikan ia pendek dan mudah. Berikut adalah contoh dokumentasi yang baik di Facebook. Jadual kandungan membawa kami ke mana kami ingin melompat ke dalam satu klik.

5. Semak dan Kemaskini

Akhir sekali, semak semula dokumentasi untuk kesilapan dan semak semula apabila perlu atau dan apabila terdapat perubahan penting pada produk, perisian, atau perpustakaan. Dokumentasi anda tidak akan berguna kepada sesiapa jika tidak selalu dikemas kini bersama produk anda.