编写类和方法的代码内文档通常在哪里？
您是否在标题（.hpp）文件或源（.cpp）文件中的相应类/方法之上编写了这样的doc-blocks？
这类事件是否有广受尊重的约定？大多数C ++项目是以一种方式而不是另一种方式来做的吗？
或者文档应该写在双方（即.hpp和.cpp文件中），也许只有一个简短的描述，一个是另一个，另一个是较长的一个？
最重要的是，是否有任何实际考虑因素使得以一种方式而不是另一种方式编写它更方便？ （例如，使用自动文档解析器和生成器，如Doxygen ...）
答案 0 :(得分：41)
<强>两个
评论任何不明显的内容，而不是（除非你的文档工具太愚蠢，以至于没有生成好的文档）。
避免将实现文档放在标头中，因为更改标头意味着makefile时间戳测试将触发包含标头的客户端应用程序的不必要的重新编译（至少在企业或商业库环境中）。出于同样的原因，我们的目标是保持标题文档的稳定性和可用性 - 足以让您不必在客户抱怨或要求示例时不断更新它。
答案 1 :(得分：16)
如果您创建了库，通常会分发已编译的库和头文件。这使得将文档放在头文件中非常有用。
答案 2 :(得分：4)
再次，两者。至于公共文档，最好是在.h中使用Doxygen可提取的格式，例如，与其他评论一样。我非常喜欢Perl记录事物的方式。 .pl（或.pm）文件本身包含文档，可以使用类似于Doxygen为C ++代码执行的工具来提取文档。此外，Doxygen允许您创建多个不同的页面，允许您包括用户手册等，而不仅仅是记录源代码或API。我通常喜欢在文学编程哲学中使用自包含.h / .hpp文件的想法。
答案 3 :(得分：3)
最重要的是，有没有 实现它的实际考虑因素 一种方式写它更方便 而不是其他方式？
假设您要在不更改代码的情况下为其中一条注释添加说明。问题是您的构建系统只会看到您更改了文件，并且不必要地假设它需要重新编译。
如果注释位于.cpp文件中，则只会重新编译该文件。如果注释位于.hpp文件中，它将重新编译依赖于该标头的每个 .cpp文件。这是一个很好的理由，希望在.cpp文件中添加您的评论。
（例如 使用自动文档解析器 和Doxygen那样的发电机......）
Doxygen允许您以任何方式撰写评论。
答案 4 :(得分：2)
我个人喜欢头文件中的文档。但是，有些人认为应该将文档放在源文件中。原因是当某些内容发生变化时，文档就会提醒您更新它。我有点同意，因为当我在源文件中更改某些内容时，我个人忘记更新标题中的 Doxygen 注释。
出于审美原因，我仍然更喜欢Doxygen评论在头文件中，旧习惯很难改变。我已经尝试了两种方法，Doxygen提供了在源文件或头文件中记录的灵活性。