（从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窃取）有些内容仅在标头中定义，例如结构，宏和
static inline函数。我只是在谈论在头文件中声明并在源文件中定义的事情。这里有一些我可以想到的参数。我倾向于在源文件中进行文档记录，因此我的“ Pro-header”参数可能有些虚弱。
Pro-header：
用户没有不需要源代码即可查看文档。
源代码可能不方便获取，甚至无法获取。
这使接口和实现进一步分离。 />
专业版源代码：
它使标题更短，使读者可以从整体上鸟瞰模块。
它会将函数的文档与函数的实现结合在一起，使您更容易看到函数按照其功能执行操作。 “现代IDE”可以做到。示例：
专业头文件：代码折叠可通过隐藏注释来帮助使注释的头文件更易于浏览。而不是头文件（声明所在的位置）。
我并不是说不要做这样的争论，而是要记住，并不是每个人都对工具感到满意您照原样使用。
#1 楼
我的看法...记录如何在头文件中使用该函数，或更准确地接近声明。
记录该函数的工作方式（如果不明显）从代码中），或更准确地说，是接近定义。
对于标题中的鸟瞰图，您不一定需要关闭的文档-您可以记录一组声明。
广义上讲，调用者应该对错误和异常感兴趣（如果仅是这样，则它们可以在抽象层中传播时进行翻译），因此应将它们记录在最相关声明。
评论
+1-即在标题中记录接口。来源中如何以及为什么的血腥细节。
–quickly_now
2011年6月15日12:30
对于没有可用资源的库标题，可以添加前后条件等，以帮助进行测试。加上合理的O（n）性能，因此图书馆用户可以明智地选择。
–帕特里克·休斯（Patrick Hughes）
2015年10月13日，0：57
自然地，有时声明和定义是相同的。
–重复数据删除器
18/12/19在14:59
@Deduplicator-当即使在特殊情况下相同的规则仍然可以得出正确的结果时，为什么还要在每个特殊情况下回显这些规则？当然，重复数据删除器不应该这样吗？
–Steve314
18/12/20在2:28
@Deduplicator-当然，如果不遵循您的建议，这是一个过大的想法，但我坚持使用。
–Steve314
18/12/20在5:23
#2 楼
如果您要使用Doxygen之类的工具（在第一个示例中请注意，它看起来像Doxygen注释，因为它以/**开头），则没关系-Doxygen将通过您的头文件和源文件查找找到所有注释以生成文档。但是，我更倾向于将文档注释放在声明所在的标头中。您的客户将处理与软件接口的标头，标头就是它们将包含在自己的源文件中的位置，这是他们首先要查看您的API外观的地方。
例如，如果您查看大多数Linux库，则您的Linux软件包管理系统通常会包含一个仅包含该库的二进制文件的软件包（对于具有需要该库的程序的“普通”用户），而您却拥有一个“ dev”包含库标头的软件包。源代码通常不直接在包装中提供。如果必须在某个地方获取库的源代码来获取API文档，那将非常麻烦。
评论
+1-一个证明，即使您使用Doxygen，也不意味着您永远不会直接从源中读取内容。 Doxygen注释有时甚至可以用作grep的标准模式，如果找到的注释接近它描述的代码，这将很方便。
–Steve314
2011年6月15日7:38
@ Steve314当然，我并不是说您永远不想看某些库的源代码-但这不是您寻找API的外观和使用方法的第一站。
–杰斯珀
2011年6月15日7:41
我还主张将与API相关的所有内容都保留在标头中（或至少保留在标头或源中），因为这样做可以避免在一个地方而不是另一个地方更新文档时可能出现的不一致性。
– jopasserat
2014年12月10日12:21
#3 楼
我们（大约25年前）通过创建可以在源文件中使用并由awk脚本扫描的#define（例如，解析为评论
嗯，我知道这种风格可能有用，但是从我的角度来看，我总是觉得这种文档太烦人了……
– osirisgothra
15年4月23日在9:42
用唐纳德·拉姆斯菲尔德（唐纳德·拉姆斯菲尔德，我不喜欢的男人）来解释一下：“您使用自己拥有的工具进行编程，而不是使用自己想要的工具进行编程。”在过去的40多年中，我使用过的每种语言至少都有一个主要的疣（如果不是更多的话）。我们的解决方案a）可行，b）当时使用的工具，c）让我们花时间把可能产生收入的代码发布出去。
– Peter Rowell
2015年4月23日在21:56
即使我可能不会选择它，它也是一种处理标头中注释的有趣方式。生成的标头是否在版本控制中？还是这是一些用于制作可重新分发源的发布过程？ （但未由开发人员使用）
–ideasman42
2015年10月12日13:24
哦，我最近在一个≥2000的项目中就看到了相同的模式，他们为自己的聪明发明感到骄傲……
– 5gon12eder
2015年10月12日在22:41
在我们的案例中，我们没有将任何生成的文件保留在版本控制下，因为它们可以轻松，直接地（重新）从跟踪文件中导出。
– Peter Rowell
2015年10月13日在15:22
#4 楼
假设这是较大项目中的代码（开发人员经常在源代码和标头之间移动），并且这不是库/中间件，其他人可能无法访问源代码，我们发现这是最好的方法...
页眉：仅在需要时提供1-2行注释。有时在一组相关功能上方的注释会很有帮助
来源：直接在函数上方的API文档（如果愿意，可以使用纯文本或doxygen）。
保留实现细节，仅与开发人员修改函数主体中的代码有关。 br />
这样做的主要原因是使注释与代码保持接近，我注意到标头中的文档往往与代码更改不同步（当然，它们不应该，但他们至少在我们的项目中这样做了。有用的信息只能放在文档字符串之一中。维护。
最后，对于大型项目-当您知道标题可能导致100或1000的文件重新出现时，倾向于不要对标题进行小的更正。当其他人更新版本控制时进行编译-也减慢了二等分错误。
#5 楼
以我的观点（相当有限且有偏见），我是专业人士认为是源代码。将文档放在源文件中时，在编辑或阅读代码时总是能看到它。我想这是习惯。
但是那只是我...
评论
如果您拥有的只是一个编译的库和头文件，则不能很好地工作。在这种情况下，头文件中的更多信息是一件好事，因为它是您唯一的接口文档。
–quickly_now
2011年6月15日12:31
您可以使用doxygen生成文档-它也从.c文件中获取。因此，您可以使用已编译的库轻松分发文档。但是麻烦在于使用IDE可以解析头文件并为您提供文档的IDE ...但是也许可以解决一些部署脚本，该脚本会将功能注释frm .c复制到.h ...
– Vit Bernatik
17年1月17日在10:51
#6 楼
注释不是文档。函数的文档通常为2K文本，可能带有图表-例如，请参阅Windows SDK中函数的文档。即使您的文档注释允许这种情况，您也将使包含注释的代码不可读。如果要生成文档，请使用文字处理器。评论
更新，这几天记录（使用Qt Creator之类的东西）来记录doxygen（或克隆）方式要容易得多，例如，在qtc中，您只需在评论前敲击几次/键，工作已为您完成。由于这样的事情，我怀疑人们会希望跳到一个文字处理器来记录他们的代码。当然，我曾经在2005年这样做，但是现在我再也不会这样做了。现在甚至使用html编辑器似乎也很陈旧。
– osirisgothra
15年4月23日在9:47
@osirisgothra Doxygen-“文档”可能很容易做到，并且肯定会生成许多快速编写的LOC，但是在大多数情况下，所生成的“文档”的价值仍然存在争议。 Doxygen注释既不是好的文档（几乎所有关键细节都被遗漏了），也不是好的注释（它们倾向于重复签名中已经显而易见的内容）。我认为nbt的说法是正确的，最好不要将真实文档与代码混合使用，因为这不利于代码的可读性。无论如何它都将不同步，这没有灵丹妙药。
–cmaster-恢复莫妮卡
2015年10月12日13:41
#7 楼
如果您的源代码的涉众（例如，一个小型库）由“用户”（将在不参与其实现的情况下使用该库功能的同级开发人员）和“开发人员”（将与您实现该库的其他开发人员）组成，然后在标题中放入“用户信息”，在源文件中放入“实施说明”。关于不要超过绝对必要的更改头文件的愿望，我想如果库不是“疯狂地变化”，它的“接口”和“功能性”不会有太大变化，而且标题注释也不应过于频繁地变化。另一方面，源代码注释将必须与源代码保持同步（“新鲜”）。
#8 楼
使用doxygen的全部目的是生成文档并使它在其他位置可访问。最多要发表一条眼线笔的评论，但那是不好的做法。如果您更改源文件中的文档，则会导致重新编译该源文件并重新链接。但是，如果您将文档放在标题中，则您实际上根本不想更改其中的任何内容，因为它会触发项目重建的重要部分。评论
在先前的7个答案中，这似乎并没有提供任何实质性的解释。
– gna
17年7月5日在9:51
来自先前7个答案的@gnat只有一个赞成针对标头的代码。那是一个完全不同的论点。
– Slava
17年7月24日在7:34
评论
相同的问题可能适用于Pascal / Delphi，其中我们没有源文件和头文件，但有接口和实现部分。另请参见stackoverflow.com/questions/355619/…