我应该把文档注释放在哪里？
在包含前向声明的头文件中，还是在包含实现的 .cpp 文件中，像这样？
//header.h
/* About foo() */
void foo();
/* About bar() */
int bar();
/* About A */
class A
{
public:
/* About A's constructor */
A();
....
}
或者
//implementation.cpp
/* About foo() */
void foo()
{
...
...
}
/* About bar */
int bar()
{
...
}
/* About A's constructor */
A::A()
{
...
}
In the header file containing the forward declarations, or in the .cpp file containing the implementations, like this?
//header.h
/* About foo() */
void foo();
/* About bar() */
int bar();
/* About A */
class A
{
public:
/* About A's constructor */
A();
....
}
Or
//implementation.cpp
/* About foo() */
void foo()
{
...
...
}
/* About bar */
int bar()
{
...
}
/* About A's constructor */
A::A()
{
...
}
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（6）
对于使用信息，最好放入标题中。那是人们首先看的地方。
如果没有人需要检查您的 .cpp 文件来弄清楚应该如何使用该组件，那么该文档就真的很成功。
For usage information, it's nicer to put into the header. That's where people would look first.
The documentation is really successful if no one has to examine your .cpp file to figure out how the component should be used.
据我所知，每次更改 .h 文件中的某些内容时，都会导致包含该头文件的所有文件被重新编译。因此，我将大部分注释放在 .cpp 文件中。
As far as I know, every time you change something in the .h file, it causes all files that have included that header file to be recompiled. For this reason, I put most of my comments in the .cpp files.
对于 C++，我将“文档注释”放在 cpp 和 h 中。
cpp 包含代码，并且对描述它们的每个主要代码元素（类、方法等）都有文档注释 - 通常使用 doxygen 或文档 XML 注释格式（尽管我不倾向于生成外部文档，但我发现它很有用）坚持标准化格式，如果/当我决定需要时，可以将其提取到外部工具）。这是全面的文档，准确解释了调用者应如何使用方法，以及任何打算修改代码的人都需要理解的任何设计细节，以便他们理解意图、“契约”以及需要理解的任何重要内容关于代码的运行。 （我为 Visual Studio 编写了一个插件 AtomineerUtils，它使得创建和更新这些注释变得快速而简单，所以一致而全面地记录这样的事情实际上并不需要太多努力）
我的标题被视为摘要（对于编译器和我自己） - 它使用单行 // 注释来简要描述每个方法。这提供了比（希望相对自文档化的）方法/参数名称更多的信息，但比 cpp 中的详细文档少很多。将其视为摘要或提醒，让您无需查看实际实现即可获得足够的详细信息，以便在大多数情况下使用该方法。
For C++, I put "documentation comments" in both the cpp and h.
The cpp contains the code, and has documentation comments on every main code element (classes, methods, etc) that describe them - typically with doxygen or Documentation XML comment format (although I don't tend to generate external docs, I find it useful to stick to a standardised format that can be extracted to external tools if/when I decide I want that). This is comprehensive documentation that explains exactly how a caller should use a method, and also any design details that will need to be understood by anyone intending to modify the code, so they understand the intent, "contract", and any important things to understand about the operation of the code. (I've written an addin for Visual Studio, AtomineerUtils, that makes creating and updating these comments quick and easy, so it's really not much effort to document things like this consistently and comprehensively)
My header is treated as a summary (both for the compiler and myself) - it uses a single-line // comment that briefly describes each method. This gives more information than the (hopefully relatively self-documenting) method/parameter names, but a lot less than the detailed documentation in the cpp. Think of it as a summary or reminder that saves you looking at the actual implementation to get enough details to use the method most of the time.
如果您使用某种自动文档生成器，则注释应该放在它告诉您应该放在哪里的地方。
否则，我将一般的“this function does X”注释放在函数定义旁边，而不是函数声明旁边（当然，除非函数在其定义处声明）。
由于函数声明可能有点庞大，因此将文档放在头文件中通常可以更轻松地立即查看与给定类相关的所有注释，从而增加其他开发人员对该类的一目了然的理解。
If you're using some sort of automatic documentation generator, comments should go wherever it tells you they should go.
Otherwise, I put general "this function does X" comments next to the function definition rather than the function declaration (unless, of course, the function is declared at its definition).
Because function declarations can be a bit bulky, putting documentation in the header file usually makes it much easier to view all comments pertaining to a given class at once, increasing the other developers' understanding of that class at a glance.
您应该将注释放在文件的声明中，即头文件或接口文件中，以 .h 扩展名结尾。
可能，为了分发，您将直接发送头文件，并以二进制形式发送 .cpp 文件，即不可读，因此如果您希望有人阅读您的注释，它们应该位于头文件内。
还有实现文档，它们只在 .cpp 文件中自然存在。
无论如何，最好使用文档工具，并学习两三个常用的 Javadoc 有用标签。您必须将开头注释更改为 /// 或 /**
You should put your comments in the declaration of the files, i.e., in the header or interface file, the one ending with .h extension.
Probably, for distribution, you are going to ship the header files directly and the .cpp ones in binary form, i.e., not readable, so if you expect someone to read your comments, they should be inside the header file.
There are also implementation documentation, that only has its natural place in the .cpp file.
In any case, it is better to use a documentation tool, and learn the two or three Javadoc usefult tags that are so common used. You have to change the opening comment to /// or /**
如果您使用 Doxygen，它将从其中一个生成文档，但如果文档同时出现在标头和实现中，则标头优先，因此请避免重复并记录标头。
此外，标头定义了用户界面，这是类的用户感兴趣的内容。此外，如果您将代码部署为库或对象代码，则标头是用户有权访问的唯一源。
If you use a Doxygen, it will generate documentation from either, but if documentation appears in both the header and the implementation, the header takes precedent, so avoid duplication and document the header.
Also the header defines the user interface which is what a user of a class is interested in. Further if you deployed the code as a library or object code, the header is the only source the user will have access to.