Di mana meletakkan blok komentar doxygen untuk perpustakaan internal - dalam file H atau CPP? [Tutup]

Akal sehat mengatakan bahwa blok komentar Doxygen harus diletakkan di file header tempat kelas, struct, enum, fungsi, deklarasi berada. Saya setuju bahwa ini adalah argumen yang kuat untuk perpustakaan yang dimaksudkan untuk didistribusikan tanpa sumbernya (hanya header dan libs dengan kode objek).

TAPI ... Saya telah memikirkan pendekatan yang berlawanan ketika saya mengembangkan pustaka internal perusahaan (atau sebagai proyek sampingan untuk saya sendiri) yang akan digunakan dengan kode sumber lengkapnya. Apa yang saya usulkan adalah untuk meletakkan blok komentar besar di file implementasi (HPP, INL, CPP, dll) agar TIDAK mengacaukan antarmuka kelas dan fungsi yang dideklarasikan di header.

Kelebihan:

• Lebih sedikit kekacauan di file header, hanya pengelompokan fungsi yang dapat ditambahkan.
• Blok komentar yang dipratinjau ketika Intellisense misalnya digunakan tidak bentrok - ini adalah cacat yang saya amati ketika saya memiliki blok komentar untuk fungsi di file .H dan memiliki definisi inline di file .H yang sama tetapi disertakan dari file .INL.

Kekurangan:

• (Yang jelas) Blok komentar tidak ada di file header tempat deklarasinya berada.

Jadi, apa yang Anda pikirkan dan mungkin sarankan?

Letakkan dokumentasi di mana orang akan membaca dan menulisnya saat mereka menggunakan dan mengerjakan kode.

Komentar kelas ditempatkan di depan kelas, komentar metode di depan metode.

Itu adalah cara terbaik untuk memastikan segala sesuatunya terjaga. Itu juga membuat file header Anda relatif ramping dan menghindari masalah menyentuh dari orang yang memperbarui dokumen metode yang menyebabkan header menjadi kotor dan memicu pembangunan kembali. Saya sebenarnya tahu orang-orang menggunakannya sebagai alasan untuk menulis dokumentasi nanti!

Saya suka memanfaatkan fakta bahwa nama dapat didokumentasikan di banyak tempat.

Di file header, saya menulis deskripsi singkat tentang metode tersebut, dan mendokumentasikan semua parameternya - ini cenderung tidak berubah daripada penerapan metode itu sendiri, dan jika ya, maka prototipe fungsi perlu diubah dalam hal apa pun .

Saya meletakkan dokumentasi format panjang di file sumber di samping implementasi aktual, sehingga detailnya dapat diubah seiring berkembangnya metode.

Sebagai contoh:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Memiliki komentar di header berarti bahwa semua pengguna kelas harus dikompilasi ulang jika ada komentar yang diubah. Untuk proyek besar, pembuat kode akan cenderung tidak memperbarui komentar di tajuk jika mereka mengambil risiko menghabiskan 20 menit berikutnya untuk membangun kembali semuanya.

Dan .. karena Anda seharusnya membaca dokumen html dan tidak menelusuri kode untuk dokumentasi, bukan masalah besar bahwa blok komentar lebih sulit ditemukan di file sumber.

Header: Lebih mudah membaca komentar karena lebih sedikit "gangguan" lainnya saat melihat file.

Sumber: Kemudian Anda memiliki fungsi aktual yang tersedia untuk membaca sambil melihat komentar.

Kami hanya menggunakan semua fungsi global yang dikomentari di header dan fungsi lokal yang dikomentari di sumber. Jika mau, Anda juga dapat menyertakan perintah copydoc untuk memasukkan dokumentasi di banyak tempat tanpa harus menulisnya beberapa kali (lebih baik untuk pemeliharaan)

Namun Anda juga bisa mendapatkan hasil disalin ke dokumentasi file yang berbeda dengan perintah sederhana. Misalnya: -

File saya1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

File SAYA1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Sekarang Anda mendapatkan dokumentasi yang sama pada kedua fungsi tersebut.

Ini memberi Anda lebih sedikit gangguan dalam file kode pada saat yang sama Anda mendapatkan dokumentasi yang ditulis di satu tempat yang disajikan di beberapa tempat di keluaran akhir.

Biasanya saya meletakkan dokumentasi untuk interface (\ param, \ return) di file .h dan dokumentasi untuk implementasi (\ details) di file .c / .cpp / .m. Doxygen mengelompokkan semuanya dalam dokumentasi fungsi / metode.

Saya meletakkan semuanya di file header.

Saya mendokumentasikan semuanya, tetapi hanya mengekstrak antarmuka publik secara umum.

Saya menggunakan QtCreator untuk pemrograman. Trik yang sangat berguna terdiri dari Ctrl-Clicking pada suatu fungsi atau metode untuk mendapatkan deklarasi di file header.

Ketika metode dikomentari di file header, Anda dapat dengan cepat menemukan informasi yang Anda cari. Jadi bagi saya, komentar harus ditempatkan di file header!

Di c ++ terkadang implementasi dapat dipisahkan antara modul header dan .cpp. Di sini tampaknya lebih bersih untuk memasukkan dokumentasi ke dalam file header karena itu adalah satu-satunya tempat di mana semua fungsi dan metode publik dijamin.