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

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注释格式(虽然我不倾向于生成外部文档,但我觉得它很有用坚持标准格式,如果/当我决定我想要的话,可以提取到外部工具.这是一个全面的文档,可以准确地解释调用者应该如何使用方法,以及任何有意修改代码的人需要理解的设计细节,这样他们就能理解意图,"契约"以及任何需要理解的重要事项.关于代码的操作.(我为Visual Studio编写了一个插件,AtomineerUtils,这使得创建和更新这些注释变得快速而简单,因此记录这样的事情并不是一件容易的事情.

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