C 函数头文件位置：.h 还是 .c？ [复制]答案

【问题标题】：C function headers location: .h or .c? [duplicate]C 函数头文件位置：.h 还是 .c？ [复制]
【发布时间】：2013-08-21 23:08:03
【问题描述】：

假设我们有函数（这里只考虑外部）int foo(int a, char *b)，通常会有一个头文件记录函数的作用，每个参数和返回值的作用等。它也可能采用 doxygen 格式。我的习惯是这样的头文件应该进入 .h 文件，因为这是定义接口的地方，读者应该在那个地方拥有所有信息。但是很多人将这些头文件保存在实际执行的 C 文件中。我也在 Linux 内核代码中看到了这一点。那我错了吗？你更喜欢哪个？

【问题讨论】：

你的意思是文档注释应该放在哪里？如果文档不是源文件本身，而是由（比如说）doxygen 预处理，那么真正的文档是 HTML/PDF 文件，所以不管它是在 .h 还是 .c .
我应该补充一点，重要的是一致性，以便未来的开发人员可以遵循可预测和可接受的编码实践。
@jxh 是的文档注释。我只考虑代码浏览场景。使用 HTML/PDF 显然无关紧要。

标签： c coding-style

【解决方案1】：

如果我有 .h 文件，我会根据自己的选择将它们放入 .h 文件中。如果我只有一个 .c 文件，我会在定义函数时记录它们，因为如果我只有一个 .c 文件，我可能仍在编码，如果我更改代码，我想更改文档。

我觉得在完成的 c 项目中文档和声明放在一个单独的文件中。代码中的文档分解了代码并且可能是多余的。

如果我在某处做出贡献，我将遵循既定惯例。

【讨论】：

"代码中的文档分解了代码..."您能否详细说明一下。我觉得源代码 ocde 文档是必不可少的。也许您指的是不同类型的文档？
当然。我主要考虑两种类型的文档：解释代码的文档和解释如何使用代码的文档。前者当然应该在代码中。但是，如果您只是说 void string_reverse(char * string, size_t string_len) 接受一个字符串和一个字符串长度并将字符串反转到位，那并没有描述代码的工作方式，那就是您将如何使用它。那应该在标题中。

【解决方案2】：

虽然头文件可以以任何方式使用，但它们主要是一种启用外部链接的机制。

您设计了一个供外部使用的 API，并将使用此 API 所需的所有内容（常量、类型、原型）放在头文件中。

所有其他的东西，这是实现的一部分，不需要被外部用户看到，可以放在源文件中（如果使用本地化到一个文件），或者可以放在私有头文件中在多个文件之间共享。后者是另一个启用外部链接但供内部使用的头文件示例。

【讨论】：

【解决方案3】：

这个问题的答案很大程度上是“这取决于”：

取决于什么？谁在阅读文档，以及他们如何访问它。

如果您正在开发一个程序，那么将文档嵌入到实现中可能是可以的，因为任何想了解您的程序的人都可以访问源代码并阅读它。您的目标受众可能是开发程序本身的开发人员，因此在 C 文件中包含文档以及他们正在处理的大部分代码是一种合适的方法。

如果您正在开发一个库，则目标受众会发生变化（或者您可能有两个目标受众）。您仍然有开发人员，他们可以使用与私有实现细节相关的更详细的文档。您还有图书馆的用户，他们只关心他们正在使用的界面；从代码浏览的角度来看，它们通常只能访问标题。

【讨论】：