Bagaimana cara saya mendokumentasikan struktur kode yang rumit?

Jika saya memiliki sepotong kode yang secara matematis atau struktural cukup rumit dan tidak dapat direduksi, bagaimana saya bisa mendokumentasikan potongan kode ini? Secara khusus, bagaimana saya dapat memastikan bahwa seseorang yang mungkin tidak memiliki keterampilan matematika atau arsitektur yang saya lakukan dapat memahaminya dari dokumentasi? Haruskah saya mendokumentasikan semua matematika juga? Tautan ke tutorial? Apakah ada pertalian bantuan visual dalam kasus struktur yang kompleks?

Ini benar-benar tergantung pada seberapa rumit kode dan matematika itu. Kode itu sendiri harus - seperti biasa - mendokumentasikan diri sendiri sebaik mungkin. Beri nama variabel dengan benar, terapkan metode logis dan ringkas (daripada fungsi-besar), tambahkan dokumentasi sebaris jika perlu (yaitu ketika tidak jelas apa yang sebenarnya dilakukan kode).

Jika Anda menggunakan algoritma yang tidak jelas, tambahkan tautan ke sumber referensi itu. Ini adalah praktik yang wajar karena memberi pengembang cara yang sangat cepat untuk mengetahui apa yang Anda lakukan. Seperti yang saya katakan, ini berguna jika itu adalah algoritma yang tidak jelas namun kompleks. Ini harus membuktikan bahwa (a) Anda melakukan sesuatu yang masuk akal, dan (b) seseorang telah menunjukkan bahwa itu berhasil.

Contoh yang baik adalah beberapa pekerjaan yang saya lakukan di sekitar pencocokan teks fuzzy. Saya melakukan penelitian besar dalam algoritma dan mengimplementasikan apa yang dikenal sebagai 'algoritma Smith-Waterman' (yang sebenarnya digunakan untuk sekuens DNA, tetapi berlaku untuk 'pencocokan' secara umum). Jadi, alih-alih hanya mengimplementasikan algoritma, saya menemukan referensi online dan menyertakan satu atau dua tautan. Seperti di atas, ini menunjukkan bahwa (a) algoritma saya cocok dengan algoritma yang dipublikasikan, dan (b) algoritma telah ditinjau dan terbukti berfungsi.

Namun ini tidak serta merta menjelaskan cara kerja kode, dan apa yang harus dilakukan berbagai kelas. Saat Anda menulis beberapa dokumentasi 'nyata' - panduan pengembang untuk sistem - Anda harus menjelaskan apa yang telah Anda lakukan dan memberikan informasi yang cukup untuk dukungan di masa mendatang. Menurut pendapat saya, dokumen ini harus dapat dibaca oleh orang yang secara teknis agnostik; tidak perlu 'dibodohi' tetapi harus mengecualikan jargon dan tidak bergantung pada asumsi pengetahuan.

Komentar seputar sumber adalah hal pertama yang harus Anda lakukan. Ini memastikan bahwa ada tautan langsung ke dokumentasi langsung oleh kode. Jika dokumentasi sangat rumit, pertimbangkan untuk hanya memposting abstrak dalam komentar, dan kemudian tautan ke beberapa dokumen eksternal yang berisi deskripsi yang lebih lengkap tentang arsitektur / algoritma yang kompleks. Namun, jika tidak terlalu rumit, pertimbangkan untuk memasukkan semua dokumentasi di satu tempat. Ini akan memaksimalkan kemungkinan kode / dokumentasi Anda tetap selaras dan dibaca bersama.

Dokumentasikan kode sejauh yang dibutuhkan tim / perusahaan Anda. Jika sebuah jr. dev akan diminta untuk mempertahankan kode, Anda mungkin harus masuk ke detail tentang beberapa matematika. Ini adalah keputusan manajemen dan mereka harus memberi Anda waktu yang diperlukan.

Saya tidak berpikir Anda harus mendokumentasikan kode begitu banyak sehingga akun Anda digantikan oleh pengembang yang lebih rendah. Jika itu menjadi masalah, Anda perlu diberi waktu untuk mendokumentasikan.

Anda tidak harus melakukan pencarian web untuk mereka.