C++：代码文档应该写在.cpp文件还是.hpp文件中？

Question

C++：代码文档应该写在.cpp文件还是.hpp文件中？

c++documentationdocumentation-generation

40

在哪里书写类和方法的内部代码文档是惯例？

您是在头文件(.hpp)中与相应的类/方法上方书写doc-blocks还是在源码(.cpp)文件中书写？

是否有一种被广泛尊重的规范？大多数C++项目都采用一种方式而不是另一种方式吗？

或者应该在两个地方编写文档(即在.hpp和.cpp文件中)，也许在一侧有一个简短的描述，在另一侧有一个更长的描述？

最重要的是，是否有任何实际考虑使其一种方式比另一种方式更方便书写？(例如使用自动文档解析器和生成器，如Doxygen...)

- augustin

4

Doxygen 旨在使你能够生成独立的公共和私有文档。 - Potatoswatter

5个回答

15

如果你制作一个库，通常会分发编译好的库和头文件。这使得将文档放在头文件中最为有用。

- Sjoerd

4

最重要的是，有没有实际考虑让它更方便地以一种方式而不是另一种方式进行编写？

假设您想在不更改代码的情况下添加对评论的澄清。问题在于，构建系统只会看到您更改了文件，并且不必要地假定需要重新编译该文件。

如果注释在.cpp文件中，则只会重新编译该文件。如果注释在.hpp文件中，它将重新编译依赖于该标头的每个.cpp文件。这是首选在.cpp文件中拥有您的注释的一个很好的理由。

Doxygen允许您以任何一种方式编写您的注释。(例如自动文档解析器和生成器，如Doxygen...)

- dan04

1

回复：“如果注释在.hpp文件中，则会重新编译依赖于该标头的每个.cpp文件。”因此，一些人认为这种行为是C++的不幸之处。请参见“为什么C++编译需要这么长时间？”（https://dev59.com/j3RC5IYBdhLWcg3wXP0C）。 - DavidRR

3

再次强调，两者都可以。至于公共文档，最好在.h文件中使用可提取的格式，例如Doxygen，正如其他人所评论的那样。我非常喜欢Perl文档编写方式。.pl（或.pm）文件本身包含了可以使用类似于Doxygen为C++代码所做的工具提取的文档。此外，Doxygen允许您创建多个不同的页面，这些页面允许您包括用户手册等，而不仅仅是记录源代码或API。总的来说，我喜欢自包含的.h/.hpp文件的思想，这符合文学编程的理念。

- Diego Sevilla

3

我个人喜欢将文档放在头文件中。然而，有些人认为文档应该放在源文件中。这是因为当某些东西发生变化时，文档会提醒你立即更新。我有些同意这种做法，因为我个人曾经忘记在更改源文件后更新头文件中的Doxygen注释。

尽管如此，出于审美原因和习惯使然，我仍然更喜欢将Doxygen注释放在头文件中。我尝试过两种方式，Doxygen允许在源文件或头文件中灵活编写文档。

- Dennis Miller

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Tony Delroy · Accepted Answer

双方:

在头文件中描述API的设计和用法：这是您向客户公开的接口。
在实现中描述替代方案/问题和决策：这是为您自己以及日后的其他维护者/增强者甚至是某些下一代系统输入的评审设计。

对于那些不明显的内容进行注释，而对于明显的内容则不要注释（除非您的文档工具无法生成良好的文档）。

避免在头文件中放置实现文档，因为更改头文件将触发客户应用程序的makefile时间戳测试，导致不必要的重新编译（至少在企业或商业库环境中）。出于同样的原因，目标是使头文件文档稳定且可用-足够好，以便您不需要根据客户投诉或要求示例来不断更新它。