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

 

在哪里编写类和方法的代码文档习惯？

您是否在头文件（.hpp）文件或源文件（.cpp）内的相应类/方法之上编写了这样的文档块？

有这样一个广受尊敬的公约吗？ 大多数C ++项目是以一种方式而不是另一种方式进行的？

还是应该在双方（即在.hpp和.cpp文件中）编写文档，可能只有一个简短的描述，另一个较长的描述？

最重要的是，是否有任何实际考虑因素使得以单向而非其他方式写作更方便？ （例如使用自动文档解析器和Doxygen等生成器）

都：

  • 描述标题中的API设计和用法：这是您的客户的公共接口。
  • 描述实施方案/实施过程中的问题和决定：这对于您自己 - 以及其他维护人员/增强人员，甚至有人将设计作为对下一代系统年度的输入进行审查。

    • 评论任何不明显的东西，并且没有任何东西（除非您的文档工具太愚蠢，无法生成良好的文档）。

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

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

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

    链接地址: http://www.djcxy.com/p/14975.html

    上一篇: C++: Where to write the code documentation: in .cpp or in .hpp files?

    下一篇: #include all .cpp files into a single compilation unit?