Apakah ada alasan logis untuk menghasilkan dokumentasi kode secara otomatis? [Tutup]

Pembuatan dokumentasi otomatis dapat dilakukan dengan berbagai alat, GhostDoc menjadi salah satu yang lebih menonjol. Namun, menurut definisi, semua yang dihasilkannya berlebihan. Dibutuhkan melihat nama-nama metode, kelas, dll dan keluaran bahasa Inggris yang mungkin menjelaskannya lebih jelas. Dalam kasus terbaik, ia melakukan apa yang sudah dapat dilakukan oleh pembaca di kepala mereka (contoh diambil dari sini ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

Yang terburuk, itu sebenarnya dapat menghasilkan dokumentasi aneh yang sebenarnya menyesatkan dalam upayanya untuk mencari tahu makna nama secara heuristik:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Tampaknya sikap dengan GhostDoc adalah, "secara intrinsik lebih baik untuk memiliki semacam dokumentasi XML formal", tetapi ketika dokumentasi itu 100% berlebihan, mengapa? Bukankah itu hanya membuang banyak ruang?

Di tempat kerja saya, kami harus mendokumentasikan semuanya, dan hampir selalu dengan dokumen yang dibuat sendiri oleh GhostDoc. Apakah Anda melakukan ini, dan apakah ada alasan rasional untuk tidak meninggalkan kode tanpa dokumen jika Anda tidak akan benar-benar menulis dokumentasi sendiri?

[...] mendokumentasikan semuanya, dan hampir selalu dengan dokumen yang dibuat sendiri oleh GhostDoc. Apakah Anda melakukan ini, dan apakah ada alasan rasional untuk tidak meninggalkan kode tanpa dokumen jika Anda tidak akan benar-benar menulis dokumentasi sendiri?

Tidak. Dokumentasi yang dihasilkan oleh GhostDoc adalah boilerplate (mirip dengan cara membuat kelas OO baru dalam IDE menciptakan boileplate untuk kelas dengan konstruktor atau sesuatu). Bagian yang berguna dari dokumentasi adalah apa yang akan terjadi setelah menambahkan boilerplate.

Meskipun Anda harus mendokumentasikan segala sesuatu di tempat kerja Anda, tampaknya rekan Anda menemukan jalan yang sempurna di sekitarnya: berpura-pura saja.

Dalam bahasa yang diketik secara statis, dokumentasi gaya Javadoc bukan untuk penulis, itu untuk konsumen. Autogenerasi hanya memudahkan penulis untuk menyimpan dokumentasi untuk dikonsumsi orang lain.

Jika Anda menggunakan bahasa yang diketik secara statis dan tidak menulis perpustakaan untuk konsumsi pihak ketiga, autogenerasi tidak banyak memberi Anda, dan menurut pengalaman saya jarang digunakan. Jika Anda menggunakan bahasa yang diketik secara dinamis, dokumentasi gaya javadoc sering digunakan untuk mendokumentasikan jenis-jenisnya, bahkan hanya untuk penggunaan internal, tetapi autogenerasi tidak mengetahui jenisnya, jadi hemat Anda untuk menghindari penyalinan boilerplate secara manual.

Either way, jangan menganggap autogeneration sebagai menghasilkan produk jadi. Anggap saja sebagai penghasil pelat untuk Anda, jadi setiap perubahan yang Anda buat secara manual adalah signifikan.

Apakah ada alasan logis untuk menghasilkan dokumentasi kode secara otomatis?

Dari sudut pandang siapa?

Jika saya menjalankan perusahaan atau grup dev, maka tidak ada alasan yang bagus. Saya setia di kamp "komentar harus menjelaskan mengapa ". Memaksa orang berkomentar kelas / fungsi / properti lebih buruk daripada tidak berharga, karena mereka ketinggalan zaman, mereka menyesatkan pembaca, mereka digunakan sebagai alasan untuk tidak membuat kode yang dapat dibaca, dan sebagainya. Komentar-komentar ini membuang-buang waktu untuk menulisnya, membaca kode, dan bug yang disebabkan oleh mereka. Beberapa orang akan berpendapat bahwa dokumen API gaya JavaDoc adalah alasan untuk melakukan komentar, tetapi bahkan di bawah argumen itu sebagian kecil dari kode Anda harus menjadi bagian dari API publik, dan JavaDoc bukan pengganti untuk dokumen API yang sebenarnya.

Sebagai pengembang, saya telah bekerja di beberapa tempat yang membutuhkan komentar di tempat-tempat ini, terlepas dari pendapat saya. Karena saya tidak punya waktu atau kesabaran untuk menulis banyak omong kosong yang tidak akan digunakan siapa pun, saya GhostDoc sebagai gantinya. Ini memungkinkan saya untuk menghabiskan waktu melakukan hal-hal yang penting. Jauh lebih efisien daripada mengubah kebijakan perusahaan.

Satu hal baik lain yang saya temukan menggunakan GhostDoc adalah berfungsi sebagai cek bahwa nama saya baik. Jika GhostDoc tidak dapat menghasilkan dokumentasi yang layak untuk suatu fungsi, itu bau bahwa fungsi atau nama parameter saya mungkin buruk. Meskipun saya tidak akan menggunakan alat ini hanya untuk ini, itu adalah efek samping kecil yang menyenangkan jika saya dibuat untuk membuang waktu saya.

EDIT : Saya salah mengerti pertanyaan aslinya; meskipun saya pikir menghasilkan dokumentasi (yaitu non-kode dokumen ) bisa sangat berharga (lihat jawaban asli mengenai Doxygen bawah), auto-menghasilkan komentar (yang merupakan sesuatu yang GhostDoc sebenarnya) terdengar gila padaku. Saya tidak dapat mengerti mengapa ada orang yang mengharapkan suatu program untuk dapat membaca kode sumber yang tidak dikomentari dan menulis komentar yang benar-benar akan memperjelasnya.

Bisa dibayangkan dengan saya bahwa sangat utilitas "pintar" komentar-generasi bisa diprogram untuk mengenali pola-pola tertentu dan menghasilkan "bagaimana" komentar -gaya; misalnya, ia dapat mengenali algoritma penghitungan varians Knuth dan memberikan komentar yang menjelaskan cara kerjanya dan mengapa algoritma naif tidak sesuai. Mungkin utilitas semacam itu bahkan dapat diprogram untuk mengenali pola desain berorientasi objek kanonik (misalnya Pabrik Abstrak) dan menyisipkan komentar yang menunjukkan pola apa yang sedang digunakan dan kelas mana yang memainkan peran apa.

Tetapi menurut pendapat saya, komentar yang paling berguna tidak menjelaskan "bagaimana" sesuatu bekerja, karena kode itu sendiri harus menunjukkan ini, tetapi " mengapa " berkomentar, menjelaskan "mengapa" hal tertentu sedang dilakukan. Seperti dicatat oleh David Hammen dalam komentar di bawah ini, untuk menghasilkan komentar "mengapa", sebuah utilitas perlu "membaca pikiran programmer." Jelas ini tidak mungkin.

Namun, berdasarkan contoh yang diberikan, tampaknya GhostDoc bahkan tidak menyelesaikan tugas untuk menciptakan komentar gaya-benar "bagaimana". Jadi, menurut saya, lebih buruk daripada tidak berguna, karena apa yang tidak menghasilkan bisa konyol dan menyesatkan (seperti dalam contoh kedua).

Jawaban asli: mengapa ekstraksi dan pemformatan dokumentasi otomatis adalah ide yang bagus

Tim perangkat lunak saya menggunakan Doxygen. Alasan utama untuk ini adalah bahwa kita memerlukan dokumentasi non-sumber-kode (yaitu dapat dibaca oleh non-programmer) fitur fitur / perilaku / dll, tetapi kami merasa bahwa itu adalah praktik yang lebih baik untuk mengintegrasikan ini ke dalam kode sumber itu sendiri daripada untuk pertahankan sebagai dokumen kedua . Ini membantu kami menjaga dokumentasi tetap sinkron dengan kode sumber (walaupun tentu saja itu tidak dapat dipastikan sepenuhnya, apalagi otomatis) dan meminimalkan overhead penulisan dokumentasi (karena dokumentasi untuk sepotong kode dapat dimasukkan secara sepele ke dalam file yang berisi kode itu sendiri).

Jadi fokus penggunaan Doxygen kami bukan untuk mengekstraksi informasi dari kode itu sendiri, tetapi untuk menjaga dokumentasi kode sumber sedekat mungkin dengan kode sumber itu sendiri.

Ini juga memungkinkan kami untuk menggunakan satu alat tunggal untuk membuat "teori operasi" yang menjelaskan seluruh basis kode kami dan beberapa set "catatan rilis" yang menjelaskan produk perangkat lunak tetapi pada kenyataannya tidak mengandung "dokumentasi kode" aktual dalam akal khas.

Adapun mengapa kita membutuhkan dokumentasi kode-kode non-sumber perilaku kita, ada dua alasan:

• Produk kami bukan hanya perangkat lunak; itu adalah alat kompleks yang mengintegrasikan banyak komponen perangkat keras, termasuk beberapa laser dan fluidics yang mewah. Kita perlu insinyur tanpa banyak latar belakang perangkat lunak untuk memiliki pemahaman yang baik tentang persis bagaimana internal berperilaku kode kita, dan mengatakan kepada mereka "membaca kode sumber" tidak akan mencapai hal ini.
• Kita harus mengikuti beberapa peraturan kualitas, beberapa diamanatkan secara internal oleh perusahaan dan lainnya diamanatkan oleh pemerintah federal. Meskipun proses kualitas (atau setidaknya bisa) sangat berharga dan bermanfaat, ini melibatkan jumlah overhead yang tidak dapat diabaikan, yang sebagian merupakan tugas tim perangkat lunak untuk menyediakan dokumentasi terperinci semacam ini dari perangkat lunak tersebut. Sekali lagi, mengintegrasikan dokumentasi ini dengan kode itu sendiri meminimalkan overhead dan membantu kami menjaga dokumentasi tetap mutakhir.

Perhatikan bahwa poin kedua sangat mirip dengan poin yang telah dibuat beberapa jawaban lain tentang manajer yang menginginkan jaminan (/ hak membual) mengetahui bahwa beberapa dokumentasi (terlepas dari kualitas) ada untuk setiap bagian dari kode sumber; cara pembingkaian itu, bagaimanapun, mengabaikan fakta bahwa dokumentasi yang dimandatkan secara eksternal sebenarnya dapat memiliki beberapa keuntungan yang sah.

Tentu saja, dokumentasi otomatis sangat membantu ketika dapat mereproduksi deskripsi yang berwawasan dan sesuai yang ditulis oleh pembuat kode. Kalau tidak, itu hanya pemformat otomatis yang dimuliakan.

Tetapi memformat tidak berguna. Ada nilai untuk dapat menemukan metode publik dari komponen besar pada satu tatapan, diurutkan, dan dijamin akan lengkap. Jika Anda memerlukan frobnickmutator, dan itu tidak ada di sana, Anda tahu itu tidak ada di sana tanpa mengarungi kode sumber. (Hasil negatif juga memiliki nilai: Anda tahu Anda harus melakukan sesuatu, dan Anda memiliki lebih banyak waktu untuk melakukannya karena Anda tidak perlu mengarungi.)

Jadi, ya, pembuatan dokumen otomatis menambah beberapa nilai. Tentu saja tidak sebanyak yang diasumsikan oleh para manajer, dan biasanya bahkan tidak sebanyak yang akan disalin oleh editor yang baik, tetapi tidak sama sekali.

Dalam bentuk ini lebih buruk daripada tidak berguna tetapi hanya karena itu bergantung pada tanda tangan publik saja (yang, dalam kasus Javadoc, tetap terlihat oleh siapa pun yang membaca dokumen API).

Tetapi dimungkinkan untuk menulis alat dokumentasi otomatis yang mempertimbangkan tubuh metode ini juga. Sebagai bukti konsep saya menulis sebuah plugin Eclipse kecil yang lumpuh yang menambahkan daftar metode lain yang dipanggil dari metode yang didokumentasikan ke Javadoc. (Tidak setiap panggilan tentu saja, Anda dapat menentukan filter, dengan paket misalnya.)

Dan saya benar-benar merasa cukup berguna ketika secara mental memetakan basis kode yang benar-benar asing. Memang, ini adalah kasus penggunaan yang sangat terbatas tapi itu pasti membantu.

Berdasarkan pengalaman itu, jawaban untuk pertanyaannya adalah: ya, tetapi kita membutuhkan banyak alat yang lebih pintar.

Pembaruan: Tentu saja pertanyaan tambahan (yang harus ditanyakan sebelum menulis segala jenis dokumentasi) adalah siapa audiens targetnya. Jika kami mendokumentasikan API publik untuk klien dari API itu, menambahkan semua detail implementasi ini adalah tidak-tidak besar karena apa pun yang Anda masukkan ke dalam Javadoc secara teknis merupakan bagian dari API.

Tetapi jika audiens target adalah pengembang lain yang bekerja pada produk yang sama, secara otomatis menambahkan informasi tentang detail implementasi, seperti metode mana yang memodifikasi atau membaca bidang tertentu yang dapat diterima dan cukup berguna.

Saya tidak tahu tentang lingkungan lain tetapi ketika datang ke proyek PHP besar (seringkali open source) yang ditulis orang lain, phpXRef adalah penyelamat mutlak (terutama jika dokumen tersebut ditempatkan online dan Google dapat mengindeksnya).

Bahkan proyek dengan komentar buruk setidaknya dapat membantu saya melacak di mana hal-hal telah didefinisikan dan di mana mereka digunakan (misalnya ketika refactoring).

Ketika dikomentari dengan baik, halaman-halaman yang dihasilkan terbentuk dekat dengan Alkitab yang sempurna untuk basis kode (untuk penggunaan saya saja).

Lebih jauh lagi, IDE pilihan saya akan secara otomatis menghasilkan blok komentar (jika saya mengetik / **) yang kira-kira 75% dari pekerjaan komentar untuk saya. Sungguh menakjubkan betapa banyak hal bodoh yang telah saya hentikan untuk dilakukan sepanjang hidup saya hanya karena saya harus menjelaskan kepada orang lain (dan calon saya) tentang apa yang saya lakukan. Ketika komentar saya untuk generator doc lebih besar dari metode ini biasanya berarti saya belum memiliki cukup kopi dan mungkin ingin berpikir sedikit lebih keras.

Blok komentar yang sama itu juga membuat teks "bantuan" penyelesaian inline jadi saya bisa melihat persis apa yang diharapkan (oleh coders lain) saat saya menulis pemanggilan fungsi. Ini adalah peningkatan produktivitas besar bagi saya (terutama dalam kasus-kasus tepi langka di mana beberapa pengembang membantu lainnya telah menulis "demi kebaikan lakukan / jangan-jangan X" - yang dapat menyelamatkan banyak rasa sakit.

Saya tidak bisa cukup menekankan betapa bermanfaatnya untuk memiliki jenis input yang diharapkan ditentukan dalam proyek-proyek PHP yang kompleks (dan sering disebut buruk) dan urutan argumen dalam metode yang jarang digunakan. Bahkan dengan kode saya sendiri, saya tidak selalu dapat mengingat argumen apa yang saya tentukan untuk sesuatu yang belum saya sentuh di zaman ini.

Dalam satu contoh itu berarti bahwa sumber masalah berulang adalah bahwa, untuk beberapa alasan yang mencerminkan buruk pada pengembang sebelumnya, beberapa fungsi dan bahkan konstanta didefinisikan dalam sejumlah besar tempat (dengan tingkat ketidakkonsistenan untuk menambahkan "kesenangan") . Itu adalah tanda untuk meninggalkan proyek.

Dalam proyek yang lebih besar yang dimulai sebelum saya bergabung, saya dapat melihat pengembang mana (dengan asumsi mereka menandai file kelas dengan nama dan email) yang membuat kelas dan hanya dapat menemukan dan berbicara dengan pengembang yang tepat sangat membantu.

Daftar tugas otomatis - menggunakan tag @todo (umum dalam jenis proyek yang saya temukan sendiri) berarti bahwa dokumentasi dapat melacak hal-hal yang memerlukan pekerjaan lebih lanjut (atau fitur yang diakui hilang). Sekali lagi IDE saya melacak ini dan itu saja bertindak sebagai panduan yang baik untuk apa yang perlu perhatian saya terlebih dahulu.

Terakhir (dan sangat penting bagi saya) itu menghilangkan overhead non-sepele dari menulis semua itu dan kemudian mencoba untuk tetap up to date ketika beberapa (baca banyak) coders melakukan perubahan dan tidak berbicara dengan pengelola dokumentasi.

Jadi, alasannya meliputi:

• Menyimpan pengembang nanti setumpuk waktu,
• Melacak di mana fungsi dipanggil (dan didefinisikan),
• Melihat kode konyol,
• Menemukan (seperti yang ditunjukkan orang lain) ketika ada sesuatu yang jelas hilang,
• Menyederhanakan refactoring (tidak pernah menyenangkan)
• (Dalam banyak kasus) mendapatkan gagasan tentang apa yang coba dilakukan pengembang (dengan asumsi ia meninggalkan beberapa catatan).
• Jika proyek ini cukup kompleks untuk mendapatkan beberapa lisensi (tidak menyenangkan), saya dapat dengan cepat melihat lisensi mana yang berlaku untuk bagian mana saja. Memang, ini adalah bonus sampingan.
• Mendapatkan gagasan tentang siapa yang harus diajak bicara tentang file proyek.
• Daftar tugas otomatis

Juga, jangan meremehkan nilai menjaga bos berambut runcing senang dengan satu sentuhan tombol.

Singkatnya "komentar dokumentasi otomatis" sangat penting untuk kebiasaan pengkodean saya. Saya yakin ada banyak yang berpikir itu payah tetapi saya juga yakin bahwa ada beberapa orang yang tahu persis apa yang saya katakan. Saya tidak tahu bagaimana saya bertahan sebelum menemukan phpXRef (dan IDE favorit saya).

Sering kali baik menggunakan generator dokumentasi untuk membuat komentar boilerplate atau "stand-in" yang kemudian direvisi oleh pengembang sebenarnya. Saya sering menggunakan fungsi auto-JavaDoc Eclipse untuk menghasilkan komentar header dengan tipe parameter dan mengembalikan nilai yang sudah diisi, kemudian cukup menambahkan "daging" dari dokumentasi.

Sebagai seorang pengembang-C # saya menggunakan Stylecop, yang mengamanatkan komentar untuk semua kelas, metode, dll. Saya membuat komentar-komentar ini secara otomatis menggunakan alat. Sebagian besar waktu, komentar yang dihasilkan oleh alat cukup dan dapat disimpulkan dengan nama objek, misalnya kelas Person memiliki dan bidang ID.

Tetapi JIKA saya ingin berkomentar metode yang tidak jelas lebih lanjut, sangat mudah untuk memperluas dokumentasi boilerplate dan beberapa penjelasan tentang apa yang dilakukannya. Sebagai contoh: Saya memiliki metode pada kelas Person saya, yang mengembalikan FirstName + Lastname, tetapi saya menambahkan sedikit docu tentang apa yang terjadi ketika salah satu dari keduanya hilang.

Singkatnya: Saya pikir dokumen boilerplate dapat merusak jika Anda tidak pernah mengubah teks yang disediakan oleh generator. Dalam hal ini, itu hanya derau baris. Tetapi jika Anda melihatnya sebagai templat, mereka menurunkan standar untuk memberikan komentar yang baik dan berguna bagi diri Anda atau konsumen Anda. Bisakah Anda menulis komentar tanpa membuat autogenerasi? Tentu, tetapi Anda harus mematuhi format (yang dalam kasus C # agak bertele-tele dan menjengkelkan untuk dihasilkan dengan tangan) dan itu menurunkan kemungkinan bahwa Anda benar-benar memberikan komentar ini di ..

Hindari Tautologi

Satu-satunya waktu Anda harus memerlukan segala jenis dokumentasi untuk kode adalah untuk menjelaskan mengapa suatu metode / fungsi melakukan sesuatu, nama harus cukup untuk apa yang dilakukannya.

Jika Anda melakukan sesuatu yang tidak idiomatis, atau melanggar prinsip paling tidak heran maka diperlukan dokumentasi.

Dokumentasi yang dihasilkan secara otomatis yang hanya formatter untuk keluaran informasi hampir dituntut oleh konsumen kode Anda. Javadoc melakukan ini dengan sangat baik.

Tidak semua hal harus didokumentasikan secara manual

Hal-hal seperti metode getXXX / setXXX harus cukup jelas, sehingga dokumentasi penghasil otomatis yang hanya memberi tahu Anda bahwa mereka ada akan diterima dengan baik.

Dokumentasi kode, setidaknya jenis "otomatis", mewakili penyebut paling umum bagi orang yang mencoba memahami aplikasi.

Pengguna paling canggih tidak akan menghargai dokumentasi kode otomatis. Mereka lebih suka memiliki dokumentasi "target" yang memberi tahu mereka (sedikit) apa yang perlu mereka ketahui.

Pengguna yang paling canggih tidak akan menghargainya karena alasan sebaliknya; mereka toh tidak akan memahaminya.

Pengguna dokumentasi kode otomatis yang paling "menghargai" adalah mereka yang "sedikit pengetahuan" adalah hal yang berbahaya. "Mereka mungkin atau mungkin tidak memahami dokumentasi (meskipun mereka cenderung), tetapi mereka akan merasa senang tentang" menjadi disimpan di loop. "Audiens ini mencakup sebagian besar tipe" manajerial ". Jika itu audiens utama Anda, dokumentasi kode otomatis mungkin merupakan hal yang baik.

jawaban sederhana untuk "mengapa menghasilkan dokumen" dapat dijawab dengan menunjukkan MSDN.

Bayangkan mencoba menulis sebuah program yang menggunakan pustaka apa pun di mana tidak ada dokumentasi API. Itu akan menjadi mimpi buruk. MSDN adalah contoh yang bagus dari jenis dokumen yang dapat dihasilkan dari kode sumber dan komentar dan membentuk sumber daya penting bagi pengembang.

Jika Anda sedang menulis aplikasi (mis. Bukan perpustakaan untuk dikonsumsi oleh orang lain) maka mungkin ada kasus untuk tidak terganggu - tetapi meskipun demikian, berapa banyak aplikasi yang besar, internal saja, tidak mengandung banyak perpustakaan bagaimanapun? Ketika Anda bergabung dengan tim seperti itu, memiliki beberapa dokumen API yang dapat dijelajahi akan sangat membantu.

Tidak ada alat yang akan menulis dokumentasi Anda untuk Anda, tetapi mereka memberi Anda pelat ketel yang harus Anda tulis secara manual, beberapa alat (seperti doxygen) juga akan menghasilkan diagram dan daftar referensi (fungsi yang dipanggil dan dipanggil misalnya) ) yang tidak akan mudah ditemukan bahkan dengan melihat kode sumber.

Akal sehat pragmatis harus diterapkan pada apa yang didokumentasikan, properti dan fungsi kecil dapat diabaikan (dan dilewati dari generasi bahkan dalam alat), tetapi tidak ada yang harus mengatakan "ada kode sumber, itu cukup dokumentasi" setiap saat .