C ++：在哪里编写代码文档：在.cpp或.hpp文件？ [英] C++: Where to write the code documentation: in .cpp or in .hpp files?

问题描述

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

您是否在标题（.hpp）文件或源（.cpp）文件中的相应类/方法上面写这些文档块？

这样的事情有一个受人尊重的惯例吗？大多数C ++项目是以一种方式而不是另一种方式吗？

或者应该将文档写在两边（即.hpp和.cpp文件中），也许一个简短的描述一个和一个更长的一个另一边？

最重要的是，有没有任何实际的考虑，使它更方便写一个方式而不是其他方式？ （例如使用自动文档解析器和Doxygen等生成器）

解决方案

两者：

• 在标题中说明API设计和使用：这是您为客户提供的公开介面。


• 描述实施中的实施替代/问题和决策：这是为你自己 - 以后 - 和其他维护者/增强者，甚至有人审查设计作为一些下一代系统年代的输入。






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





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




Where is it customary to write the in-code documentation of classes and methods?

Do you write such doc-blocks above the corresponding class/method in the header (.hpp) file, or within the source (.cpp) file?

Is there a widely respected convention for such things? Do most C++ projects do it one way rather than the other?

Or should documentation be written on the two sides (i.e. in the .hpp and the .cpp files), maybe with one short description one one side and a longer one on the other side?

Most importantly, are there any practical considerations that makes it more convenient to write it one way rather than the other way ? (E.g. the use of automatic documentation parsers and generators like Doxygen...)

解决方案

Both:

• Describe the API design and usage in the header: that's your public interface for clients.
• Describe the implementation alternatives / issues and decisions in the implementation: that's for yourself - later - and other maintainers/enhancers, even someone reviewing the design as input to some next-gen system years hence.

Comment anything that's not obvious, and nothing that is (unless your documentation tool's too stupid to produce good documentation without).

Avoid putting implementation docs in the headers, as changing the header means makefile timestamp tests will trigger an unnecessary recompilation for client apps that include your header (at least in an enterprise or commercial library environment). For the same reason, aim to keep the header documentation stable and usable - good enough that you don't need to keep updating it as clients complain or ask for examples.

这篇关于C ++：在哪里编写代码文档：在.cpp或.hpp文件？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！