C++ C++；：在哪里编写代码文档：在.cpp或.hpp文件中？

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

您是在头（.hpp）文件中的相应类/方法上方还是在源（.cpp）文件中写入此类文档块

这类事情是否有一个广受尊重的惯例？大多数C++项目是单向的而不是其他的吗？ 或者文档应该写在两面（即在.hpp和.cpp文件中），可能一面写一个简短的描述，另一面写一个较长的描述

---

最重要的是，是否有任何实际的考虑因素使得以一种方式编写比以另一种方式编写更方便？（例如，使用自动文档解析器和生成器，如Doxygen…）

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

两者：

• 在标题中描述API的设计和使用：这是客户机的公共接口
• 描述实施中的实施备选方案/问题和决策：这是为您自己-稍后-和其他维护人员/增强人员，甚至是审查设计作为下一代系统的输入的人员

---

注释任何不明显的东西，不要注释任何明显的东西（除非你的文档工具太愚蠢了，没有它就无法生成好的文档）

---

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

同样，两者都是如此。至于公共文档，最好是在.h中使用可以用Doxygen提取的格式，例如，正如其他人所评论的那样。我非常喜欢Perl编写文档的方式。PL（O.PM）文件本身包含文档，可以使用与DoxEng++为C++代码类似的工具来提取。此外，Doxygen允许您创建多个不同的页面，允许您包括用户手册等，而不仅仅是记录源代码或API。在识字编程的理念中，我通常喜欢独立的.h/.hpp文件。

我个人喜欢头文件中的文档。然而，有些人认为文档应该放在源文件中。原因是当某些内容发生更改时，文档就在那里提醒您进行更新。我有点同意，因为我个人在更改源文件中的某些内容时忘记了更新标题中的Doxygen注释

出于美观的原因，我仍然喜欢将Doxygen注释放在头文件中，而且旧习惯很难改变。我已经尝试了这两种方法，Doxygen提供了在源文件或头文件中进行文档记录的灵活性

最重要的是，有没有 这是出于实际考虑 用一种方式写更方便 而不是相反

假设您希望在不更改代码的情况下向其中一条注释添加澄清。问题是构建系统只会看到您更改了文件，并且不必要地认为需要重新编译该文件

如果注释在.cpp文件中，它将只重新编译该文件。如果注释位于.hpp文件中，它将重新编译依赖于该头的每个.cpp文件。这是一个很好的理由，您更喜欢将您的评论放在.cpp文件中

（例如： 自动文档分析器的使用 和发电机，如强氧…）

---

Doxygen允许您以任意一种方式撰写评论。

两者都可以。Doxygen的设计目的是让您可以生成单独的公共和私有文档。通常，我在编写函数定义之前先编写文档。也就是说，除非有打字错误，否则必须更改文档通常也意味着函数的更改，因此您无论如何都必须重新编译。@ereOn:我认为@Tony suggestion仍然适用：如果它是接口的一部分，它就在标题中，如果它是一个实现细节（出于X原因，使用容器a而不是容器B）然后，对实现代码的更改需要对实现文档进行更改，但用户甚至不应该注意到。“对不明显的（**和**[…]）进行注释。”合理的建议。评论越少越好。单元测试也是一种记录Ap.RE用法的好方法：“如果注释在.HPP文件中，它将重新编译依赖于该报头的.CPP文件。”因此，有些人认为这种行为是C++的一个不幸的方面。看见