在包含前向声明的头文件中，还是在包含实现的 .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()
{
...
}
【问题讨论】：
标签： c++ header documentation
有关使用信息，最好放在标题中。这是人们首先看的地方。
如果没有人必须检查您的 .cpp 文件来确定应该如何使用该组件，那么该文档是非常成功的。
【讨论】：
据我所知，每次更改 .h 文件中的某些内容时，都会重新编译包含该头文件的所有文件。出于这个原因，我将大部分 cmets 放在 .cpp 文件中。
【讨论】：
对于 C++，我将“文档 cmets”放在 cpp 和 h 中。
cpp 包含代码，并且在描述它们的每个主要代码元素（类、方法等）上都有文档 cmets - 通常使用 doxygen 或文档 XML 注释格式（虽然我不倾向于生成外部文档，但我如果/当我决定需要时，坚持使用可以提取到外部工具的标准化格式很有用）。这是一个全面的文档，它准确地解释了调用者应该如何使用一个方法，以及任何想要修改代码的人都需要理解的设计细节，以便他们理解意图、“合同”和任何需要理解的重要事项关于代码的操作。 （我已经为 Visual Studio 编写了一个插件 AtomineerUtils，它可以快速轻松地创建和更新这些 cmets，因此无需花费太多精力就可以始终如一地全面记录此类内容）
我的标题被视为摘要（编译器和我自己） - 它使用单行 // 注释来简要描述每个方法。这提供了比（希望是相对自记录的）方法/参数名称更多的信息，但比 cpp 中的详细文档要少得多。可以将其视为一个总结或提醒，让您无需查看实际实现即可获得足够的详细信息以在大多数情况下使用该方法。
【讨论】：
如果您使用某种自动文档生成器，那么 cmets 应该去任何它告诉您它们应该去的地方。
否则，我把通用“这个函数做X” cmets放在函数定义而不是函数声明旁边（除非，当然，函数是在其定义中声明的）。
由于函数声明可能有点庞大，将文档放在头文件中通常可以更轻松地一次查看与给定类有关的所有 cmets，从而增加其他开发人员对该类的一目了然的理解。
【讨论】：
您应该将 cmets 放在文件的声明中，即头文件或接口文件中，以 .h 扩展名结尾。
可能，对于分发，您将直接发送头文件，而 .cpp 则以二进制形式发送，即不可读，因此如果您希望有人阅读您的 cmets，它们应该在头文件中。
还有一些实现文档，它们只在 .cpp 文件中自然存在。
无论如何，最好使用文档工具，并学习两个或三个 Javadoc 非常常用的有用标签。您必须将开头的评论更改为 /// 或 /**
//header.h
/** @brief About power()
@see lpower
@param x The base to power
@param y The exponent, number of times to multiply base by itself
@return x^y
*/
int power(int x, int y);
【讨论】：
int power(int base, int exponent);。然后你可以删除 6 行 cmets 而不删除任何信息完全。而且我可能能够同时在屏幕上显示两个以上的功能。如果你想写小说，至少要帮用户一个忙，把它放在一个单独的文本文件中，而不是放在代码中。
@brief 部分。通过查看函数签名，参数和返回值应该是显而易见的。我的态度是很有道理的。是你的吗？
如果您使用 Doxygen，它会从其中任何一个生成文档，但如果文档同时出现在标头和实现中，则标头优先，因此避免重复并记录标头。
标头还定义了类用户感兴趣的用户界面。此外，如果您将代码部署为库或目标代码，则标头是用户可以访问的唯一来源。
【讨论】：