记录我们的 C++ 的最佳场所代码
在阅读了一些关于 Doxygen 的内容之后，我有点困惑在哪里记录我的变量、函数等。它应该在实现文件（源代码）中还是在其接口（头文件）中。
对此的最佳实践是什么？
After having some readings about Doxygen I'm a bit confused where to document my variable, function etc. Should it be in the implementation file(source) or in its interface(header file).
What is the best practise regarding that.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
将文档放在标题中。需要注意的一件非常重要的事情是不要过度记录。不要开始为每个变量和函数编写注释，尤其是当您所做的只是陈述显而易见的内容时。例子...
下面的评论是显而易见的并且没有帮助。所有的评论只要看一下函数就很清楚了。
相反，您应该记录该函数在极端情况下的行为方式。例如，如果参数错误怎么办？如果它返回一个指针，谁负责删除该指针？程序员在使用该功能时还应该注意哪些事项？另外
，我建议您只在头文件中记录接口：不要谈论函数如何执行某些操作，只告诉做什么确实如此。如果您想解释实际的实现，我会在源文件中添加一些相关的（正常）注释。
Place documentation in your headers. And one very important thing to look out for is to not overdocument. Don't start writing a comment for every single variable and function, especially if all you do is state the obvious. Examples...
This comment below is obvious and unhelpful. All the comment says is perfectly clear just by looking at the function.
You should instead document how the function behaves in extreme situations. For example, what does it do if the parameters are wrong? If it returns a pointer, whose responsibility is it to delete the pointer? What other things should programmers keep in mind when using this function? etc.
Also, I would advice you only document the interface in the header files: don't talk about how the function does something, tell only what it does. If you want to explain the actual implementation, I'd put some relevant (normal) comments in the source file.
您应该只记录头文件，尽管有时这可能很困难。
You should aim to document only your header files, although at times it may prove difficult.
我一般建议将文档放在头文件中，并从用户的角度对其进行记录。
在极少数情况下，将注释放在源文件中（甚至放在单独的文件中）可能是有益的，例如，如果
可能还有其他不太强烈的原因：有些人喜欢源代码中的注释，因为它可以使头文件保持小而整洁。其他人希望文档如果接近实际实现就更容易保持最新（他们可能会记录该函数的功能而不是如何使用它）。
I generally recommend to put the documentation in the header file, and documented it from a user perspective.
In rare situations it may be beneficial to put the comments in the source file (or even in a separate file), for instance if
There can be other, less strong reasons: some people like comments in the source code, because it keeps the header file small and tidy. Others expect the documentation to be easier to keep up to date if it is close to the actual implementation (with the risk that they documented what the function does instead of how to use it).