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

Question

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

您是否在标题(.hpp)文件或源(.cpp)文件中的相应类/方法之上编写了这样的doc-blocks？

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

或者文档应该写在双方(即.hpp和.cpp文件中),可能只有一个简短的描述,一个是另一个更长的一个？

最重要的是,是否有任何实际的考虑因素使得以一种方式而不是另一种方式编写它更方便？(例如使用Doxygen等自动文档解析器和生成器......)

Answer 1

都:

评论任何不明显的东西,没有任何东西(除非你的文档工具太愚蠢,没有产生好的文档).

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

通常,在编写函数定义之前,我会编写文档.也就是说,除非有拼写错误,否则必须更改文档通常意味着函数的更改,所以无论如何都必须重新编译. (3认同)
@ereOn:我认为@Tony建议仍然很好:如果它是接口的一部分,它在标题中,如果它是一个实现细节(*使用容器A代替B而不是原因X*)那么改变了实现代码需要更改实现文档,但用户甚至不应注意. (2认同)
"评论任何不明显的事情(**而且没有**[...])." 合理的建议.评论越少越好.单元测试也是记录API使用情况的好方法. (2认同)

Answer 2

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