Đặt các khối nhận xét doxygen cho thư viện nội bộ - trong H hoặc trong tệp CPP ở đâu? [đóng cửa]

Theo cách hiểu thông thường, các khối chú thích Doxygen phải được đặt trong tệp tiêu đề nơi chứa các lớp, cấu trúc, enum, hàm, khai báo. Tôi đồng ý rằng đây là một đối số hợp lý cho một thư viện có nghĩa là được phân phối mà không có nguồn của nó (chỉ tiêu đề và lib với mã đối tượng).

NHƯNG ... Tôi đã nghĩ đến cách tiếp cận hoàn toàn ngược lại khi tôi đang phát triển một thư viện nội bộ cho công ty (hoặc như một dự án phụ cho chính tôi) sẽ được sử dụng với mã nguồn đầy đủ của nó. Những gì tôi đề xuất là đặt các khối chú thích lớn trong các tệp triển khai (HPP, INL, CPP, v.v.) để KHÔNG làm lộn xộn giao diện của các lớp và hàm được khai báo trong tiêu đề.

Ưu điểm:

• Ít lộn xộn hơn trong các tệp tiêu đề, chỉ có thể thêm phân loại các chức năng.
• Các khối nhận xét được xem trước khi Intellisense chẳng hạn được sử dụng không xung đột - đây là một khiếm khuyết mà tôi đã quan sát thấy khi tôi có khối nhận xét cho một hàm trong tệp .H và có định nghĩa nội tuyến của nó trong cùng tệp .H nhưng được bao gồm từ tệp .INL.

Nhược điểm:

• (Điều hiển nhiên) Các khối chú thích không có trong tệp tiêu đề nơi có các khai báo.

Vì vậy, bạn nghĩ gì và có thể đề xuất điều gì?

Đặt tài liệu ở nơi mọi người sẽ đọc và viết nó khi họ đang sử dụng và làm việc trên mã.

Lớp nhận xét đi trước lớp, bình luận phương pháp đi trước phương pháp.

Đó là cách tốt nhất để đảm bảo mọi thứ được duy trì. Nó cũng giữ cho các tệp tiêu đề của bạn tương đối gọn gàng và tránh vấn đề đụng chạm đến việc mọi người cập nhật tài liệu phương pháp khiến tiêu đề bị bẩn và kích hoạt xây dựng lại. Tôi thực sự đã biết mọi người sử dụng nó như một cái cớ để viết tài liệu sau này!

Tôi thích tận dụng thực tế là tên có thể được ghi lại ở nhiều nơi.

Trong tệp tiêu đề, tôi viết một mô tả ngắn gọn về phương thức và ghi lại tất cả các tham số của nó - những tham số này ít có khả năng thay đổi hơn so với việc triển khai chính phương thức và nếu có thì nguyên mẫu hàm cần phải được thay đổi trong mọi trường hợp .

Tôi đặt tài liệu định dạng dài trong các tệp nguồn bên cạnh việc triển khai thực tế, vì vậy các chi tiết có thể được thay đổi khi phương pháp phát triển.

Ví dụ:

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;
}

Có nhận xét trong tiêu đề nghĩa là tất cả người dùng của một lớp phải được biên dịch lại nếu nhận xét bị thay đổi. Đối với các dự án lớn, các lập trình viên sẽ ít có xu hướng cập nhật nhận xét trong tiêu đề hơn nếu họ mạo hiểm dành 20 phút tiếp theo để xây dựng lại mọi thứ.

Và .. vì bạn phải đọc tài liệu html và không duyệt qua mã cho tài liệu, nên không có vấn đề gì lớn khi các khối nhận xét khó tìm hơn trong tệp nguồn.

Tiêu đề: Dễ dàng đọc các nhận xét hơn vì ít có "tiếng ồn" khác khi xem các tệp.

Nguồn: Sau đó, bạn có các chức năng thực tế có sẵn để đọc trong khi xem các nhận xét.

Chúng tôi chỉ sử dụng tất cả các hàm toàn cục được nhận xét trong tiêu đề và các hàm cục bộ được nhận xét trong nguồn. Nếu muốn, bạn cũng có thể bao gồm lệnh copydoc để chèn tài liệu vào nhiều nơi mà không cần phải viết nhiều lần (tốt hơn để bảo trì)

Tuy nhiên, bạn cũng có thể sao chép kết quả sang tài liệu tệp khác bằng một lệnh đơn giản. Ví dụ :-

File1.h của tôi

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

MY file1.c

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

Bây giờ bạn nhận được cùng một tài liệu về cả hai chức năng.

Điều này giúp bạn ít nhiễu hơn trong các tệp mã đồng thời bạn nhận được tài liệu được viết ở một nơi được trình bày ở nhiều nơi trong đầu ra cuối cùng.

Thông thường, tôi đặt tài liệu cho giao diện (\ param, \ return) trong tệp .h và tài liệu cho việc triển khai (\ chi tiết) trong tệp .c / .cpp / .m. Doxygen nhóm mọi thứ trong tài liệu chức năng / phương pháp.

Tôi đặt mọi thứ trong tệp tiêu đề.

Tôi ghi lại mọi thứ, nhưng chỉ trích xuất giao diện chung.

Tôi đang sử dụng QtCreator để lập trình. Một thủ thuật rất hữu ích bao gồm Ctrl-Nhấp vào một hàm hoặc phương thức để lấy khai báo trong tệp tiêu đề.

Khi phương thức được nhận xét trong tệp tiêu đề, bạn có thể nhanh chóng tìm thấy thông tin bạn đang tìm kiếm. Vì vậy, đối với tôi, nhận xét nên được đặt trong tệp tiêu đề!

Trong c ++, đôi khi việc triển khai có thể được phân tách giữa mô-đun tiêu đề và .cpp. Ở đây, có vẻ gọn gàng hơn khi đưa tài liệu vào tệp tiêu đề vì đó là nơi duy nhất mà tất cả các chức năng và phương thức công khai được đảm bảo.