Question

在包含前向声明的头文件中，还是在包含这些实现的.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()
{
    ...
}

Answer 1

对于使用信息，放入标题会更好。这就是人们首先要看的地方。

如果没有人必须检查你的.cpp文件以确定应该如何使用该组件，那么文档就非常成功。

Answer 2

据我所知，每次更改.h文件中的内容时，都会导致重新编译包含该头文件的所有文件。出于这个原因，我将大部分注释放在.cpp文件中。

Answer 3

对于C ++，我将“文档注释”放在cpp和h中。

cpp包含代码，并且对描述它们的每个主要代码元素（类，方法等）都有文档注释 - 通常使用doxygen或Documentation XML注释格式（尽管我不倾向于生成外部文档，I发现如果/当我决定要这样做时，坚持使用可以提取到外部工具的标准化格式是有用的。这是一个全面的文档，可以准确地解释调用者应该如何使用方法，以及任何有意修改代码的人需要理解的设计细节，以便他们理解意图，“合同”以及任何需要理解的重要事项。关于代码的操作。（我已经为Visual Studio编写了一个插件，AtomineerUtils，这使得创建和更新这些注释变得简单快捷，所以记录这样的事情并不是一件容易的全面而且很全面。

我的标题被视为摘要（对于编译器和我自己而言） - 它使用单行//注释来简要描述每个方法。这提供了比（希望相对自我记录）方法/参数名称更多的信息，但比cpp中的详细文档少得多。将其视为摘要或提醒，可以节省您查看实际实现，以获取足够的详细信息以便在大多数时间使用该方法。

Answer 4

如果你正在使用某种自动文档生成器，评论应该放在它告诉你应该去的地方。

否则，我在函数 definition 旁边放置了一般“this function does X”注释，而不是函数声明（除非，当然，函数在其定义中声明）。

因为函数声明可能有点笨重，所以将文档放在头文件中通常可以更容易地同时查看与给定类相关的所有注释，从而使其他开发人员对该类的理解一目了然。

Answer 5

你应该把你的评论放在文件的声明中，即在标题或接口文件中，以.h扩展名结尾。

或许，对于分发，您将直接发送头文件，并以。二进制形式发送.cpp文件，即不可读，所以如果您希望有人阅读您的注释，它们应该在头文件中。< / p>

还有一些实现文档，它只在.cpp文件中有自然的位置。

在任何情况下，最好使用文档工具，并学习常用的两个或三个Javadoc usefult标记。您必须将开场评论更改为///或/ **

//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);

Answer 6

如果您使用Doxygen，它将从其中任何一个生成文档，但如果文档和实现中都出现文档，则标题优先，因此请避免重复并记录标题。

此标题还定义了用户界面，这是一个类用户感兴趣的内容。此外，如果您将代码部署为库或目标代码，则标头是用户可以访问的唯一来源。

我应该在哪里放置文档注释？

6 个答案: