Metodologi untuk mendokumentasikan basis kode yang ada

Saya bekerja sebagai bagian dari tim pada aplikasi yang sudah ada yang tidak memiliki dokumentasi sebaris, juga tidak memiliki dokumentasi teknis. Karena saya telah mengerjakan berbagai laporan bug pada aplikasi, saya telah menulis semacam jejak remah roti untuk saya sendiri - nomor bug di berbagai tempat sehingga pengembang selanjutnya dapat merujuk ke nomor bug itu untuk melihat apa yang sedang terjadi.

Pertanyaan saya adalah:

Apa metode yang paling efisien untuk mendokumentasikan kode ini? Haruskah saya mendokumentasikan saat saya menyentuh area (metode virus, jika Anda mau), atau haruskah saya mendokumentasikan dari setiap bagian sendiri, dan tidak mengikuti jalur yang bercabang ke area lain dari aplikasi? Haruskah saya memasukkan komentar sebaris di mana sebelumnya tidak ada (dengan takut bahwa saya mungkin salah mengidentifikasi kode apa yang dilakukan)?

Metode apa yang akan Anda gunakan untuk secara akurat dan cepat mendokumentasikan aplikasi yang agak besar yang tidak memiliki dokumentasi inline yang ada, atau referensi inline untuk dokumentasi eksternal?

Mendokumentasikan basis kode warisan

Saya sangat merekomendasikan mengikuti aturan scout dengan basis kode lama. Mencoba mendokumentasikan proyek warisan secara mandiri tanpa mengerjakannya tidak akan pernah terjadi.

Dokumentasi dalam kode

Yang paling penting adalah menggunakan fasilitas dokumentasi di lingkungan pengembangan yang Anda pilih, sehingga itu berarti pydoc untuk python, javadoc di java atau komentar xml dalam C #. Ini memudahkan untuk menulis dokumentasi pada saat yang sama dengan menulis kode.

Jika Anda mengandalkan untuk kembali dan mendokumentasikan sesuatu nanti, Anda mungkin tidak menyiasati hal itu, tetapi jika Anda melakukannya saat Anda menulis kode, maka apa yang perlu didokumentasikan akan menjadi segar dalam pikiran Anda. C # bahkan memiliki opsi untuk mengeluarkan peringatan kompilasi jika dokumentasi XML tidak lengkap atau tidak konsisten dengan kode aktual.

Tes sebagai dokumentasi

Aspek penting lainnya adalah memiliki integrasi yang baik dan pengujian unit.

Seringkali dokumentasi berkonsentrasi pada apa yang dilakukan kelas dan metode secara terpisah, melompati cara mereka digunakan bersama untuk menyelesaikan masalah Anda. Tes sering menempatkan ini ke dalam konteks dengan menunjukkan bagaimana mereka berinteraksi satu sama lain.

Demikian pula, tes unit sering menunjukkan ketergantungan eksternal secara eksplisit melalui mana hal-hal yang perlu diejek .

Saya juga menemukan bahwa menggunakan pengembangan yang digerakkan oleh Test, saya menulis perangkat lunak yang lebih mudah digunakan, karena saya menggunakannya langsung dari kata go. Dengan kerangka pengujian yang baik, membuat kode lebih mudah untuk diuji dan membuatnya mudah digunakan seringkali merupakan hal yang sama.

Dokumentasi tingkat tinggi

Akhirnya ada apa yang harus dilakukan tentang tingkat sistem dan dokumentasi arsitektur. Banyak yang menganjurkan menulis dokumentasi seperti itu di wiki atau menggunakan Word atau pengolah kata lain, tetapi bagi saya tempat terbaik untuk dokumentasi tersebut juga di samping kode, dalam format teks biasa yang ramah sistem kontrol versi.

Sama seperti dengan dokumentasi dalam-kode, jika Anda menyimpan dokumentasi tingkat yang lebih tinggi dalam repositori kode Anda, maka Anda akan cenderung memperbaruinya. Anda juga mendapatkan manfaat bahwa ketika Anda mengeluarkan versi XY kode, Anda juga mendapatkan versi XY dokumentasi. Selain itu, jika Anda menggunakan format ramah VCS, maka itu berarti mudah untuk bercabang, berbeda, dan digabungkan, seperti halnya kode Anda.

Saya sangat suka pertama , karena mudah untuk menghasilkan halaman html dan dokumen pdf dari itu, dan jauh lebih ramah daripada LaTeX , namun masih dapat menyertakan ekspresi matematika LaTeX saat Anda membutuhkannya.

Pertanyaan rumit. Pada dasarnya, saya akan menggunakan metode "refactoring", yang akan saya nyatakan sebagai "jika Anda menyentuh kode, mendokumentasikannya".

Tapi tepatnya; ketika masalah muncul, dan karena Anda harus terbiasa dengan kode untuk memperbaiki bug yang terjadi, saya akan mengatakan Anda harus menggunakan keakraban itu untuk menulis komentar pada kode itu secara khusus; pada dasarnya, motivasi untuk memperbaiki bug pada saat itu memaksa Anda untuk cukup terbiasa dengan kode untuk dapat mendokumentasikannya. Dan untuk alasan itu, saya akan curiga mengikuti cabang yang tidak terkait ATAU mendokumentasikan fungsi yang tidak terkait, karena pada saat itu, jika Anda tidak melakukan pengujian kode secara aktif (untuk memverifikasi perbaikan bug Anda), maka sulit untuk sepenuhnya yakin bahwa Anda mengerti persis apa yang kode lakukan dan mengapa. (Saya tidak masuk ke masalah yang juga bisa sulit untuk mengetahui dengan tepat apa dan mengapa kode melakukan apa yang dilakukannya bahkan ketika menguji perbaikan bug; Anda

Pendekatan ini harus cenderung memaksimalkan keakuratan, dengan pengorbanan kecepatan keseluruhan, tetapi tidak memengaruhi kebutuhan Anda untuk mempertahankan kode terlalu parah pada saat yang sama. Jika tugas perbaikan bug Anda kecil, tentu saja, Anda dapat menjelajah ke "wilayah yang tidak dikenal" dan mulai mendokumentasikan di sana, tetapi jika Anda (seperti kebanyakan dari kita) tidak dapat menemukan cukup waktu dalam sehari untuk memperbaiki kode dan mendokumentasikannya, ini adalah kompromi yang bagus.

Satu hal yang perlu diperhatikan juga; Anda harus memiliki dokumentasi eksternal yang baik. Anda mengatakan bahwa kode Anda tidak memiliki referensi ke dokumentasi eksternal; Saya harap demi Anda bahwa dokumentasi eksternal semacam itu ada. Jika tidak, saya akan benar-benar menulis dokumentasi eksternal itu sebagai prioritas utama Anda; sesuatu pada tingkat spesifikasi fungsional, saya pikir, sangat penting untuk semua proyek perangkat lunak besar. Alasannya adalah bahwa spesifikasi fungsional, atau dokumentasi tingkat tinggi dari formulir itu, dapat membantu mencegah "fitur creep" atau "fitur drift" dalam perangkat lunak apa pun; dan penyimpangan fitur (khususnya) dapat merusak dokumentasi karena dapat menyebabkan dokumentasi menjadi usang. (Saya mendefinisikan creep fitur sebagai penambahan progresif (dan menjengkelkan) fitur ke perangkat lunak; drift fitur, di sisi lain, adalah tempat serangkaian tindakan yang oleh perangkat lunak lambat berubah seiring waktu. Creep fitur bersifat ADDITIVE, artinya biasanya melibatkan peningkatan set fungsionalitas perangkat lunak; fitur drift, di sisi lain, adalah zero-sum; satu per satu, satu fungsi tepi terdefinisi untuk melakukan sesuatu yang berbeda, sampai perangkat lunak melakukan sesuatu yang sama sekali berbeda dari yang semula dimaksudkan. Penyimpangan fitur jarang terjadi, tetapi MATI untuk dokumentasi.)

Satu aplikasi yang saya kembangkan bersama selama dua tahun memiliki kekurangan dokumentasi yang serius. Pada titik tertentu menjadi jelas bahwa kami akan mengirimkan aplikasi ke pengembang lain yang akan memeliharanya sejak saat itu, jadi kami harus mendokumentasikan kodenya.

Untuk menangani ruang lingkup raksasa dari proses dokumentasi, saya akan mencoba dan mendokumentasikan semua kode dalam fitur tertentu atau bagian dari aplikasi pada hari tertentu. Saya tidak memiliki pola tertentu, tetapi desakan untuk melakukan beberapa hal setiap hari, dan mendapatkan rasa penyelesaian dengan mendokumentasikan seluruh file atau bagian dari aplikasi setiap hari.

Butuh berbulan-bulan untuk mendokumentasikan seluruh aplikasi, tetapi dalam setengah jam (maks) sehari itu tidak pernah benar-benar memakan jadwal proyek dan menghindari banyak kebosanan yang sejalan dengan dokumentasi.

Kami menggunakan dokumentasi XML dalam C #, dan menyediakan cukup fitur dan struktur untuk membuat dokumentasi mudah. Bahkan jika Anda tidak mendokumentasikan aplikasi C #, pola memiliki ringkasan pendek pertama diikuti oleh komentar sangat tidak berguna.

Saya akan mendokumentasikan ketika saya menambahkan / memodifikasi kode. Selain itu saya juga akan mendokumentasikan API publik atau antarmuka antar modul. Jika Anda mendokumentasikan semua kode, Anda mungkin tidak melihat ROI untuk waktu yang dihabiskan. Mungkin bermanfaat untuk menggunakan sesuatu seperti wiki untuk mengatur dokumentasi eksternal saat Anda mengembangkannya. Dokumen paling berguna yang saya rujuk ketika saya memulai proyek terakhir saya adalah dokumen arsitektur. Ini termasuk informasi tentang teknologi yang digunakan dan memberikan pandangan tingkat tinggi tentang bagaimana aplikasi itu berlapis.

Saya akan menggunakan komentar Doxygen. Doxygen memiliki lebih banyak format output yang kebanyakan format gratis lainnya dan mudah dipelajari.

Anda bahkan dapat mempertimbangkan untuk menyewa kontraktor untuk melakukan ini, karena sebagian dari kita melakukannya untuk mencari nafkah. Namun, dengan pilihan ini Anda masih harus berkomitmen untuk meninjau dokumen.

Teknik umum lainnya adalah untuk menetapkan pengembang baru untuk mendokumentasikan kode. Kemudian mintalah setiap orang baru melewatinya saat mereka bangun dengan kecepatan. Ketahuilah bahwa beberapa devs memandang ini sebagai mendapatkan saluran akar - hanya diperlukan dalam kasus langsung, LOL.

Sebelum Anda mulai mendokumentasikan apa pun, kembangkan standar. Ini bisa sesederhana memastikan Anda menulis beberapa baris di atas fungsi atau kelas header ke sesuatu yang lebih resmi dan verbose (seperti javadoc). Sebelum siapa pun dapat memeriksa kode, dokumentasinya harus memenuhi standar itu.

Apa yang saya temukan berfungsi dengan baik adalah menambahkan komentar yang ditulis dengan baik sebelum header fungsi ke fungsi yang saya buat yang sebelumnya tidak didokumentasikan, dan menambahkan komentar sebaris untuk apa pun yang saya tambahkan. Anda ingin menghindari mendokumentasikan kode yang belum Anda sentuh. Lebih buruk memiliki komentar buruk daripada tidak ada komentar, dan jika Anda mendokumentasikan ini dengan 'cepat', Anda mungkin akan menulis komentar buruk.