Trong các ngôn ngữ phân biệt giữa tệp "nguồn" và "tiêu đề" (chủ yếu là C và C ++), tốt hơn là ghi lại các chức năng trong tệp tiêu đề:
(lấy từ 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);
hoặc trong tập tin nguồn?
(lấy từ 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)
{
...
Lưu ý rằng một số thứ chỉ được xác định trong tiêu đề, chẳng hạn như cấu trúc, macro và static inlinehàm. Tôi chỉ nói về những thứ được khai báo trong tệp tiêu đề và được xác định trong tệp nguồn.
Dưới đây là một số đối số tôi có thể nghĩ ra. Tôi đang nghiêng về tài liệu trong tệp nguồn, vì vậy các đối số "Tiêu đề Pro" của tôi có thể hơi yếu.
Tiêu đề chuyên nghiệp:
- Người dùng không cần mã nguồn để xem tài liệu.
- Nguồn có thể bất tiện, hoặc thậm chí là không thể có được.
- Điều này giữ cho giao diện và thực hiện xa hơn.
Nguồn chuyên nghiệp:
- Nó làm cho tiêu đề ngắn hơn rất nhiều, cho người đọc một cái nhìn toàn cảnh về mô-đun nói chung.
- Nó ghép tài liệu của một chức năng với việc thực hiện của nó, làm cho nó dễ dàng hơn để thấy rằng một chức năng thực hiện những gì nó nói.
Khi trả lời, xin hãy cảnh giác với các lập luận dựa trên những công cụ và "IDE hiện đại" có thể làm gì. Ví dụ:
- Tiêu đề chuyên nghiệp: Việc gấp mã có thể giúp làm cho các tiêu đề nhận xét có thể điều hướng nhiều hơn bằng cách ẩn các nhận xét.
- Pro-source: tính năng của cscope
Find this global definitionđưa bạn đến tệp nguồn (nơi định nghĩa là) chứ không phải tệp tiêu đề (nơi khai báo ).
Tôi không nói rằng đừng đưa ra những lập luận như vậy, nhưng hãy nhớ rằng không phải ai cũng thoải mái với các công cụ bạn sử dụng như bạn.