C++: Nơi để viết tài liệu mã: trong .cpp hoặc trong tệp .hpp?

Question

Ở đâu thông lệ để viết tài liệu trong mã của các lớp và phương pháp?

Bạn có viết các khối tài liệu như vậy ở trên lớp/phương thức tương ứng trong tệp tiêu đề (.hpp) hoặc trong tệp (.cpp) nguồn không?

Có quy ước được tôn trọng rộng rãi cho những thứ như vậy không? Hầu hết các dự án C++ có làm theo cách này hay không?

Hoặc tài liệu nên được viết ở hai bên (ví dụ: trong tệp .hpp và .cpp), có thể chỉ với một mô tả ngắn một bên và một phần dài hơn ở phía bên kia?

Quan trọng nhất, có bất kỳ cân nhắc thực tế nào giúp thuận tiện hơn khi viết theo một cách thay vì cách khác không? (Ví dụ: việc sử dụng các trình phân tích cú pháp tài liệu tự động và các trình tạo như Doxygen ...)

Answer 1

Cả:

• Mô tả việc thiết kế và sử dụng API trong tiêu đề: đó là giao diện công cộng của bạn cho khách hàng.
• Mô tả các lựa chọn thay thế/vấn đề và quyết định trong việc triển khai: đó là cho bản thân bạn - sau này - và các nhà bảo trì/người nâng cao khác, thậm chí có người xem xét thiết kế này làm đầu vào cho một số năm hệ thống tiếp theo.

Bình luận mọi thứ không rõ ràng và không có gì là (trừ khi công cụ tài liệu của bạn quá ngu ngốc để tạo tài liệu tốt).

Tránh đặt tài liệu triển khai trong tiêu đề, khi thay đổi tiêu đề có nghĩa là các kiểm tra dấu thời gian makefile sẽ kích hoạt biên dịch lại không cần thiết cho ứng dụng khách bao gồm tiêu đề của bạn (ít nhất trong môi trường doanh nghiệp hoặc thư viện thương mại). Vì lý do tương tự, hãy giữ cho tài liệu tiêu đề ổn định và có thể sử dụng - đủ tốt để bạn không cần phải tiếp tục cập nhật tài liệu đó khi khách hàng khiếu nại hoặc yêu cầu ví dụ.

Answer 2

Nếu bạn tạo một thư viện, bạn thường phân phối thư viện đã biên dịch và các tệp tiêu đề. Điều này làm cho nó hữu ích nhất để đặt tài liệu trong các tập tin tiêu đề.

Answer 3

Một lần nữa, cả hai. Đối với các tài liệu công khai, nó là tốt đẹp để được trong. H với một định dạng giải nén với Doxygen, ví dụ, như nhận xét khác. Tôi thích cách viết tài liệu của Perl. Tệp .pl (hoặc .pm) bao gồm tài liệu tự nó có thể được trích xuất bằng cách sử dụng một công cụ tương tự như những gì Doxygen làm cho mã C++. Ngoài ra, Doxygen cho phép bạn tạo nhiều trang khác nhau, cho phép bạn bao gồm các hướng dẫn sử dụng, v.v., không chỉ ghi lại mã nguồn hoặc API. Tôi thường thích ý tưởng của một tập tin .h/.hpp khép kín trong triết lý lập trình biết chữ.

Answer 4

Cá nhân tôi thích tài liệu trong các tệp tiêu đề. Tuy nhiên, có một số người tin rằng tài liệu nên được đặt trong các tập tin nguồn. Lý do là khi một cái gì đó thay đổi, tài liệu là đúng có nhắc nhở bạn để cập nhật nó. Tôi phần nào đồng ý, như cá nhân tôi đã quên cập nhật các ý kiến ​​Doxygen trong tiêu đề khi tôi thay đổi một cái gì đó trong các tệp nguồn.

Tôi vẫn thích nhận xét của Doxygen hơn trong tệp tiêu đề vì lý do thẩm mỹ và thói quen cũ khó thay đổi. Tôi đã thử cả hai và Doxygen cung cấp sự linh hoạt của tài liệu hoặc trong các tập tin nguồn hoặc tiêu đề.

Answer 5

Quan trọng nhất, là có bất kỳ cân nhắc thực tế mà làm cho nó thuận tiện hơn để viết nó một cách chứ không phải theo cách khác?

Giả sử bạn muốn thêm làm rõ cho một trong các nhận xét của mình mà không thay đổi mã. Vấn đề là hệ thống xây dựng của bạn sẽ chỉ thấy rằng bạn đã thay đổi tệp và không cần thiết giả thiết rằng nó cần phải được biên dịch lại.

Nếu nhận xét nằm trong tệp .cpp, nó sẽ chỉ biên dịch lại một tệp đó. Nếu các nhận xét nằm trong tệp .hpp, nó sẽ biên dịch lại mỗi tệp .cpp phụ thuộc vào tiêu đề đó. Đây là một lý do tốt để thích có ý kiến ​​của bạn trong các tập tin .cpp.

(ví dụ như các sử dụng phân tích cú pháp tài liệu tự động và máy phát điện như Doxygen ...)

Doxygen cho phép bạn viết bình luận của bạn trong hai cách.