C++：在哪里编写代码文档：在 .cpp 或 .hpp 文件中？ [关闭]答案

【问题标题】：C++: Where to write the code documentation: in .cpp or in .hpp files? [closed]C++：在哪里编写代码文档：在 .cpp 或 .hpp 文件中？ [关闭]
【发布时间】：2011-04-04 02:53:47
【问题描述】：

通常在哪里编写类和方法的代码内文档？

您是在头文件 (.hpp) 或源文件 (.cpp) 中的相应类/方法上方编写此类文档块吗？

对于此类事情是否有一个广受尊重的约定？大多数 C++ 项目都是以一种方式而不是另一种方式来做的吗？

或者文档应该写在两侧（即在 .hpp 和 .cpp 文件中），也许一侧有一个简短的描述，另一侧有一个较长的描述？

最重要的是，是否有任何实际考虑使得以一种方式而不是另一种方式编写它更方便？（例如，使用像 Doxygen 这样的自动文档解析器和生成器......）

【问题讨论】：

两者。 Doxygen 的设计目的是让您可以生成单独的公共和私人文档。

标签： c++ documentation documentation-generation

【解决方案1】：

两者：

在标头中描述 API 设计和使用：这是您为客户端提供的公共接口。
描述实施替代方案/问题和实施中的决策：这是为您自己（稍后）和其他维护者/增强者，甚至是审查设计的人，作为未来几年某些下一代系统的输入。

评论任何不明显的东西，不要评论任何东西（除非你的文档工具太愚蠢而无法生成好的文档）。

避免将实现文档放在标头中，因为更改标头意味着 makefile 时间戳测试将触发包含您标头的客户端应用程序的不必要重新编译（至少在企业或商业图书馆环境中）。出于同样的原因，目标是保持标头文档的稳定性和可用性 - 足够好，以至于您不需要在客户抱怨或要求示例时不断更新它。

【讨论】：

通常，我在编写函数定义之前编写文档。也就是说，除非有错别字，否则必须更改文档通常也意味着函数的更改，因此无论如何您都必须重新编译。
@ereOn：我认为@Tony 的建议仍然适用：如果它是接口的一部分，它就在标头中，如果它是一个实现细节（使用容器 A 而不是 B原因 X) 则实现代码的更改需要更改实现文档，但用户甚至不应该注意到。
"评论任何不明显的内容（**并且没有任何内容**[...]）。中肯的建议。 cmets越少越好。单元测试也是记录 API 使用情况的好方法。

【解决方案2】：

如果您创建一个库，您通常会分发编译后的库和头文件。这使得将文档放在头文件中最有用。

【讨论】：

【解决方案3】：

同样，两者都是。至于公共文档，很高兴在 .h 中使用 Doxygen 可提取的格式，例如，正如其他人评论的那样。我非常喜欢 Perl 记录事物的方式。 .pl（或 .pm）文件本身包含文档，可以使用类似于 Doxygen 为 C++ 代码所做的工具提取这些文档。此外，Doxygen 允许您创建几个不同的页面，允许您包含用户手册等，而不仅仅是记录源代码或 API。我通常喜欢文学编程哲学中自包含 .h/.hpp 文件的想法。

【讨论】：

【解决方案4】：

最重要的是，有没有使其成为现实的考虑因素用一种方式写更方便而不是其他方式？

假设您想在不更改代码的情况下向其中一个 cmets 添加说明。问题是您的构建系统只会看到您更改了文件，并且不必要地假定它需要重新编译。

如果 cmets 在 .cpp 文件中，它只会重新编译那个文件。如果 cmets 在 .hpp 文件中，它将重新编译依赖于该标头的每个 .cpp 文件。这是将您的 cmets 放在 .cpp 文件中的一个很好的理由。

（例如使用自动文档解析器和像 Doxygen 这样的生成器...）

Doxygen 允许您以任何一种方式编写 cmets。

【讨论】：

RE: "如果 cmets 在 .hpp 文件中，它将重新编译 每个 。 cpp 文件依赖于该头文件。” 出于这个原因，一些人认为这种行为是 C++ 的一个不幸方面。见Why does C++ compilation take so long?。

【解决方案5】：

我个人喜欢头文件中的文档。但是，有些人认为文档应该放在源文件中。原因是当某些事情发生变化时，文档就在那里提醒您更新它。我有点同意，因为当我更改源文件中的某些内容时，我个人忘记更新标头中的 Doxygen cmets。

出于美学原因，我仍然更喜欢将 Doxygen cmets 放在头文件中，而且旧习惯很难改变。我都试过了，Doxygen 提供了在源文件或头文件中记录的灵活性。

【讨论】：