Apakah lebih baik mendokumentasikan fungsi dalam file header atau file sumber?

Dalam bahasa yang membedakan antara file "sumber" dan "header" (terutama C dan C ++), apakah lebih baik mendokumentasikan fungsi dalam file header:

(dicuri dari CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

atau dalam file sumber?

(dicuri dari PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Perhatikan bahwa beberapa hal didefinisikan hanya dalam tajuk, seperti struct, makro, dan static inlinefungsi. Saya hanya berbicara tentang hal-hal yang dideklarasikan dalam file header dan didefinisikan dalam file sumber.

Inilah beberapa argumen yang bisa saya pikirkan. Saya cenderung mendokumentasikan file sumber, jadi argumen "Pro-header" saya mungkin agak lemah.

Pro-header:

• Pengguna tidak memerlukan kode sumber untuk melihat dokumentasi.
  • Sumbernya mungkin tidak nyaman, atau bahkan tidak mungkin, untuk diperoleh.
  • Ini membuat antarmuka dan implementasi semakin terpisah.

Pro-sumber:

• Itu membuat header jauh lebih pendek, memberikan pembaca pandangan mata-burung dari modul secara keseluruhan.
• Ini memasangkan dokumentasi dari suatu fungsi dengan implementasinya, membuatnya lebih mudah untuk melihat bahwa suatu fungsi melakukan apa yang dikatakannya.

Saat menjawab, harap waspada terhadap argumen berdasarkan alat apa dan "IDE modern" dapat lakukan. Contoh:

• Pro-header: Pelipatan kode dapat membantu membuat tajuk komentar lebih mudah dinavigasi dengan menyembunyikan komentar.
• Pro-sumber: cscope 's Find this global definitionfitur membawa Anda ke file sumber (di mana definisi ini) daripada file header (di mana deklarasi ini).

Saya tidak mengatakan jangan membuat argumen seperti itu, tetapi ingatlah bahwa tidak semua orang merasa nyaman dengan alat yang Anda gunakan.

Pandangan ku...

• Dokumentasikan cara menggunakan fungsi dalam file header, atau lebih dekat dengan deklarasi.

• Dokumentasikan bagaimana fungsi bekerja (jika tidak jelas dari kode) dalam file sumber, atau lebih tepatnya, dekat dengan definisi.

Untuk hal burung-mata di header, Anda tidak perlu dokumentasi yang dekat - Anda dapat mendokumentasikan kelompok deklarasi sekaligus.

Secara umum, penelepon harus tertarik pada kesalahan dan pengecualian (jika hanya mereka dapat diterjemahkan karena mereka menyebar melalui lapisan abstraksi) sehingga ini harus didokumentasikan dekat dengan deklarasi yang relevan.

Jika Anda akan menggunakan alat seperti Doxygen (perhatikan dalam contoh pertama, itu benar-benar terlihat seperti komentar Doxygen karena dimulai dengan /**) maka tidak terlalu masalah - Doxygen akan melihat melalui header dan file sumber Anda dan menemukan semua komentar untuk menghasilkan dokumentasi.

Namun, saya akan lebih cenderung untuk meletakkan komentar dokumentasi di header, di mana deklarasi tersebut berada. Klien Anda akan berurusan dengan header untuk berinteraksi dengan perangkat lunak Anda, header adalah apa yang akan mereka sertakan dalam file sumber mereka sendiri dan di situlah mereka akan mencari terlebih dahulu untuk melihat seperti apa API Anda.

Jika Anda melihat sebagian besar pustaka Linux misalnya, sistem manajemen paket Linux Anda sering memiliki paket yang hanya berisi binari perpustakaan (untuk pengguna "normal" yang memiliki program yang memerlukan pustaka) dan Anda memiliki paket "dev" yang berisi tajuk untuk perpustakaan. Kode sumber biasanya tidak diberikan secara langsung dalam satu paket. Akan sangat merepotkan jika Anda harus mendapatkan kode sumber perpustakaan di suatu tempat untuk mendapatkan dokumentasi API.

Kami memecahkan masalah ini (sekitar 25 tahun yang lalu) dengan membuat banyak # definisi (mis. Publik, pribadi, dll., Yang teratasi menjadi <tidak ada>) yang dapat digunakan dalam file sumber dan dipindai oleh skrip awk (horor !) untuk menghasilkan file .h secara otomatis. Ini berarti bahwa semua komentar tinggal di sumber dan disalin (bila perlu) ke dalam file .h yang dihasilkan. Saya tahu itu Sekolah Tua yang cantik, tetapi sangat menyederhanakan dokumentasi inline semacam ini.

Dengan asumsi ini adalah kode dalam proyek yang lebih besar (di mana pengembang akan sering berpindah antara sumber dan tajuk) , dan menyediakan ini bukan perpustakaan / perangkat menengah, di mana orang lain mungkin tidak memiliki akses ke sumber, saya telah menemukan ini berfungsi terbaik...

• Header:
  Terse 1-2 komentar baris, hanya jika mereka diperlukan.
  Terkadang komentar di atas sekelompok fungsi terkait juga membantu.
• Sumber:
  Dokumentasi pada API langsung di atas fungsi (teks biasa atau doxygen jika Anda suka) .
• Menyimpan detail implementasi, hanya relevan dengan pengembang yang memodifikasi kode di badan fungsi.

Alasan utama untuk ini adalah untuk menjaga komentar dekat dengan kode, saya perhatikan dokumen di header cenderung tidak sinkron dengan perubahan pada kode lebih sering (tentu saja tidak seharusnya, tetapi mereka lakukan dalam proyek kami di paling tidak) . Pengembang juga dapat menambahkan dokumentasi di bagian atas fungsi ketika mereka membuat beberapa perubahan, bahkan jika ada dokumen header ... di tempat lain. Menyebabkan double-up atau info berguna hanya berada di salah satu dokumen.

Tentu saja Anda dapat memilih konvensi dan memastikan semua pengembang mengikuti, saya baru saja menemukan konvensi di atas yang paling alami dan paling tidak menyulitkan untuk dipertahankan.

Terakhir dari semua, untuk proyek-proyek besar - ada kecenderungan untuk tidak membuat koreksi kecil di header ketika Anda tahu itu akan menyebabkan berpotensi 100 atau 1000 file untuk dikompilasi ulang ketika orang lain memperbarui kontrol versi - memperlambat kesalahan membagi dua juga.

Menurut saya (agak terbatas dan bias), saya berpikir cara kode pro-sumber. Ketika saya melakukan sedikit demi sedikit dalam C ++, saya biasanya mengedit file header sekali dan kemudian saya tidak pernah benar-benar kembali untuk melihatnya.

Ketika saya menempatkan dokumentasi di file sumber, saya selalu melihatnya ketika saya mengedit atau membaca kode. Saya kira itu adalah kebiasaan.

Tapi itu hanya aku ...

Komentar bukan dokumentasi. Dokumentasi untuk fungsi biasanya 2K teks, mungkin dengan diagram - lihat misalnya dokumentasi untuk fungsi di Windows SDK. Bahkan jika komentar-ke-dok Anda memungkinkan hal seperti itu, Anda akan membuat kode yang berisi komentar tidak dapat dibaca. Jika Anda ingin menghasilkan dokumentasi, gunakan pengolah kata.

Jika pemangku kepentingan kode sumber Anda (misalnya, perpustakaan kecil) terdiri dari "pengguna" (sesama pengembang yang akan menggunakan fungsionalitas perpustakaan Anda tanpa terlibat dalam implementasinya) dan "pengembang" (Anda dan pengembang lain yang akan mengimplementasikan perpustakaan) , lalu letakkan "informasi pengguna" di header dan "catatan implementasi" di sumber.

Berkenaan dengan keinginan untuk tidak mengubah file header lebih dari yang benar-benar diperlukan - saya kira jika perpustakaan Anda tidak "dalam perubahan perubahan gila", bahwa "antarmuka" dan "fungsionalitas" tidak akan banyak berubah, dan tidak ada haruskah komentar tajuk berubah terlalu sering. Di sisi lain, komentar kode sumber harus tetap disinkronkan ("segar") dengan kode sumber.

Inti dari penggunaan doxygen adalah Anda menghasilkan dokumentasi dan membuatnya dapat diakses di tempat lain. Sekarang semua dokumentasi di header hanyalah sampah yang membuatnya lebih sulit untuk dengan cepat menemukan pernyataan fungsi yang diperlukan, dan mungkin kelebihannya. Satu komentar liner adalah maksimum yang seharusnya ada di sana, tetapi bahkan itu adalah praktik yang buruk. Penyebab jika Anda mengubah dokumentasi di sumber, Anda mengkompilasi ulang sumber itu dan menghubungkan kembali. Tetapi jika Anda meletakkan dokumen di header Anda benar-benar tidak ingin mengubah sedikit pun di sana, karena itu akan memicu bagian penting dari pembangunan kembali proyek.