Dokumentasi kode: Publik vs Non-Publik?

Saya salah satu pengembang yang memiliki pola pikir bahwa kode yang ditulis harus jelas dan dibaca seperti buku.

NAMUN, ketika mengembangkan kode pustaka untuk digunakan orang lain, saya mencoba memasukkan sebanyak mungkin dokumentasi dalam file header; yang memunculkan pertanyaan: Apakah mendokumentasikan metode yang non-publik bahkan sepadan dengan waktu? Mereka tidak akan menggunakannya secara langsung, pada kenyataannya, mereka tidak bisa. Pada saat yang sama jika saya mendistribusikan kode mentah (walaupun, dengan enggan) metode-metode non-publik akan terlihat dan mungkin perlu dijelaskan.

Hanya mencari beberapa standar dan praktik yang Anda semua lihat atau gunakan dalam perjalanan Anda.

Saya tidak akan pernah mempertimbangkan menghilangkan dokumentasi untuk internal hanya karena "pengguna akhir" tidak akan menggunakannya; pemeliharaan kode lebih dari cukup alasan untuk memasukkan komentar dokumentasi untuk semua komponen, bahkan terutama untuk internal yang cenderung menjadi bagian yang paling kompleks (dan seringkali berubah).

Yang mengatakan, mungkin ada kasus yang valid untuk dibuat agar mereka terbatas pada kode sumber non-header (daripada didokumentasikan secara publik), untuk menjaga abstraksi.

Ini semua agak subyektif, ingatlah.

Ok, saya menambahkan cara saya berkomentar / mendokumentasikan juga untuk gambar untuk variasi. Dasar pemikirannya adalah bahwa saya menghindari menggambarkan fungsi atau fungsi anggota yang hanya dideklarasikan di header. Di satu sisi saya takut menambahkan terlalu banyak noise ke header. Di sisi lain, dokumentasi bersama dengan definisi lebih mudah untuk dipelihara oleh pengelola. Doxygen tidak peduli dengan cara apa pun dan dapat menyaring kemaluan jika diperlukan.

Di header kelas:

• termasuk tajuk (mengapa)
• definisi kelas selalu (tujuan dan tanggung jawab)
• fungsi virtual murni selalu (kontrak penuh)
• fungsi inline kecuali pengambil getar jelas
• tipe yang dinyatakan lain kecuali cukup jelas
• anggota data statis (mengapa)
• anggota data lain kecuali cukup jelas
• makro jika ada (kontrak dan mengapa)

Kode implementasi di kelas:

• deklarasi lokal sama seperti pada header
• definisi fungsi selalu (kontrak penuh)
• definisi fungsi anggota selalu (kontrak penuh atau referensi ke root virtual override)
• variabel statis didefinisikan jika ada (tujuan mengapa)

Di tajuk template:

• di atas bergabung dan
• tipe cocok / tidak cocok untuk argumen templat dan
• seberapa baik kesesuaian terdeteksi secara statis

Bagian private:awal dari privat adalah semua dokumentasi yang seharusnya dibutuhkan oleh pengguna.

Dokumentasi adalah setiap hari sepadan, itu membantu untuk menjelaskan kasus penggunaan dan cerita secara singkat. Betapapun kodenya cukup jelas, ia tidak bisa menjelaskan bisnis semudah beberapa baris cerita. Kode pasti akan mengharuskan pengguna untuk menindaklanjuti logika selain memahami apa yang sedang terjadi. :-) 2 sen saya ...

Pastinya!

Kode itu harus mendokumentasikan diri sendiri adalah slogan untuk dijalani. Namun, saya akan mengatakan bahwa kode pribadi memerlukan sebanyak mungkin dokumentasi, jika tidak lebih, dari kode publik, karena biasanya di sinilah biasanya asumsi paling banyak terjadi, hanya karena pembuat kode berasumsi bahwa kode itu akan tetap dalam kegelapan. . Jadi, beberapa bulan kemudian, ketika sebuah bug menghampiri Anda, Anda akan menghabiskan waktu mencoba mengingat apa ide di balik kode (mungkin Anda sendiri) yang menulis.

Dokumentasi seharusnya tidak ada sebagai hadiah yang bagus untuk orang lain. Dokumentasi, di semua wajahnya (nama variabel yang dipilih dengan baik, nama kelas yang didokumentasikan sendiri, kode yang terorganisir dengan baik, metode yang tersegmentasi dengan baik, dll) adalah hadiah untuk semua orang yang mungkin berhubungan dengan kode Anda, termasuk diri Anda.