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.