在头文件或源文件中记录函数是否更好？

在区分“源”文件和“头文件”（主要是C和C ++）的语言中，最好在头文件中记录函数：

（从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);

或在源文件中？

（从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)
{
...

请注意，某些内容仅在标头中定义，例如结构，宏和static inline函数。我只是在谈论在头文件中声明并在源文件中定义的内容。

这是我能想到的一些论点。我倾向于在源文件中进行文档记录，因此我的“ Pro-header”参数可能有些弱。

专业头：

• 用户不需要源代码即可查看文档。
  • 来源可能不方便，甚至无法获取。
  • 这使接口和实现进一步分开。

原始资料：

• 它使标题大大缩短，使读者可以从整体上鸟瞰模块。
• 它将功能的文档与其实现配对，从而更容易看出该功能是否按其要求执行。

在回答时，请警惕基于什么工具和“现代IDE”可以做什么的争论。例子：

• 专业标题：代码折叠可通过隐藏注释来帮助使注释的标题更易于浏览。
• Pro-source：cscope的Find this global definition功能将您带到源文件（定义所在的位置），而不是头文件（声明所在的位置）。

我并不是说不要提出这样的论据，但要记住，并不是每个人都对使用的工具感到满意。

我的观点...

• 在头文件中记录如何使用该函数，或更准确地说，在声明附近。

• 在源文件中（或更准确地说，接近定义）记录功能的工作方式（如果从代码中看不到）。

对于标题中的鸟瞰图，您不一定需要关闭文档-您可以一次记录一组声明。

从广义上讲，调用者应该对错误和异常感兴趣（如果仅是错误和异常，则它们可以在通过抽象层传播时进行翻译），因此应在相关声明的附近进行记录。

如果您要使用Doxygen之类的工具（在第一个示例中请注意，由于它以开头，所以它看起来确实像是Doxygen注释/**），但这并不重要-Doxygen将浏览您的标头和源文件并查找所有注释以生成文档。

但是，我更倾向于将文档注释放在声明所在的标头中。您的客户将处理与软件接口的标头，标头就是它们将包含在其自己的源文件中的位置，这就是他们首先要查看您的API外观的地方。

例如，如果您查看大多数Linux库，则Linux软件包管理系统通常具有仅包含该库的二进制文件的软件包（对于具有需要该库的程序的“普通”用户），而您具有一个“ dev”软件包包含库的头。源代码通常不直接在包装中提供。如果您必须在某个地方获取库的源代码以获取API文档，那将非常麻烦。

我们（大约25年前）通过创建可以在源文件中使用并由awk脚本扫描的#define（例如，解析为<nothing>的public，private等）解决了此问题。 ！）自动生成.h文件。这意味着所有注释都驻留在源代码中，并在适当时被复制到生成的.h文件中。我知道这很老派，但是大大简化了这种内联文档。

假设这是较大项目中的代码（开发人员经常在源代码和标头之间移动），并且提供的不是库/中间件，而其他人可能无法访问源代码，那么我发现这可行最好...

• 标头：
  仅当需要时，简短的1-2行注释。
  有时，在一组相关功能上方的注释也很有帮助。
• 来源：
  函数正上方的API文档（纯文本或doxygen，如果您愿意）。
• 保留实现细节，仅与开发人员修改函数主体中的代码有关。

这样做的主要原因是使注释与代码保持接近，我注意到标头中的文档往往与代码更改不同步（当然不应该这样做，但是在我们的项目中确实如此）至少）。开发人员也可以在进行某些更改时在功能顶部添加文档，即使其他地方有标头文档。导致重复或有用的信息仅出现在文档字符串之一中。

当然，您可以选择一个约定并确保所有开发人员都遵循，我刚刚发现该约定最自然，维护起来也就麻烦最少。

最后，对于大型项目- 当您知道标题可能导致100或1000的文件在其他人更新版本控制时重新编译时，倾向于不要对标题进行小更正-也会减慢二等分错误。

以我的观点（相当有限且有偏见），我是专业的源代码思维方式。当我用C ++进行零碎工作时，通常会编辑一次头文件，然后再也不会真正回头看它。

当我将文档放在源文件中时，在编辑或阅读代码时总是会看到它。我想这是习惯。

但这就是我...

注释不是文档。函数的文档通常为2K文本，可能带有图表-例如，请参阅Windows SDK中函数的文档。即使您的文档注释允许这种情况，您也将使包含注释的代码不可读。如果要生成文档，请使用文字处理器。

如果您的源代码的涉众（例如，一个小型库）由“用户”（将在不参与其实现的情况下使用该库的功能的同级开发人员）和“开发人员”（您和将要实现该库的其他开发人员）组成，然后将“用户信息”放在标题中，并将“实施说明”放在源代码中。

关于不要更改头文件超出绝对必要的愿望-我想如果您的库不是“疯狂的变化”，那么“接口”和“功能性”将不会有太大变化，并且两者都不会标头注释的更改过于频繁。另一方面，源代码注释将必须与源代码保持同步（“新鲜”）。

使用doxygen的全部目的是您生成文档并使其可在其他地方访问。现在，标头中的所有文档都只是垃圾，这使得快速发现所需的函子声明以及其重载更加困难。最多只能有一条内衬评论，应该放在那儿，但这甚至是不好的做法。如果您更改源文件中的文档，则会导致重新编译该源文件并重新链接。但是，如果您将文档放在标题中，则您实际上根本不想更改其中的任何内容，因为它将触发项目重建的重要部分。