我该把文档注释放在哪里？

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()
{
    ...
}

- wrongusername

---

例如：http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml - hB0

Answer 1

为了使用信息，最好将其放在头部。那是人们首先会查看的地方。

如果没有人需要检查你的 .cpp 文件才能弄清楚组件的使用方式，那么文档就非常成功了。

- Johan Kotlinski

---

如果您正在以非开放许可证分发您的库或其他内容，您可以轻松地将代码文档与头文件一起分发。+1。 - Travis Gockel

如果我不必检查标题，那么这份文档就非常成功。 - jalf

Answer 2

据我所知，每当你修改.h文件时，都会导致所有包含该头文件的文件重新编译。因此，我将大部分注释放在.cpp文件中。

- Ray Zhou

---

注释未被编译！ - user415789

不，但修改它们会强制重新编译。 - Johan Kotlinski

Answer 3

对于C++，我在cpp和h文件中都放置了“文档注释”。

cpp包含代码，并在每个主要的代码元素（类、方法等）上都有文档注释，描述它们-通常使用doxygen或Documentation XML注释格式（尽管我不倾向于生成外部文档，但我发现坚持一个标准化格式很有用，可以在需要时将其提取到外部工具中）。这是全面的文档，说明调用者应如何使用方法，以及任何设计细节，这些细节需要为打算修改代码的任何人所理解，因此他们理解意图，“合同”以及有关代码操作的重要内容。（我为Visual Studio编写了一个插件AtomineerUtils，使创建和更新这些注释变得快捷轻松，因此花费不多的时间来一致且全面地记录这样的事情。）

我的头文件被视为摘要（对于编译器和我自己） - 它使用单行//注释来简要描述每个方法。这提供了比（希望相对自文档化的）方法/参数名称更多的信息，但比cpp中的详细文档少得多。把它当作一个摘要或提醒，可以节省查看实际实现以获取足够细节以大多数情况下使用该方法的时间。

- Jason Williams

Answer 4

如果您正在使用某种自动文档生成器，注释应放置在其指示的位置。

否则，我会将一般的“此函数执行X”注释放在函数定义旁边，而不是函数声明旁边（除非当然，在定义时声明函数）。

由于函数声明可能有点臃肿，在头文件中放置文档通常使得查看与给定类相关的所有注释变得更加容易，从而增加其他开发人员对该类的理解。

- ClosureCowboy

---

除非在定义时声明函数，否则您不应该将其放在函数定义旁边。那么您应该把它放在哪里呢？ ;) - leviathanbadger

Answer 5

你应该将注释放在文件的声明中，即在头文件或接口文件中，以.h扩展名结尾的文件。

可能，为了分发，你要直接发送头文件，而将.cpp文件以二进制形式发送，即不可读的形式。因此，如果你期望有人阅读你的注释，它们应该在头文件中。

还有实现文档，只有在.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);

- Baltasarq

---

这只是一个简单的例子。例子本身就是为了显而易见而设计的。你的态度是无法被辩解的。 - Baltasarq

“不合理的？”这是一个有趣的观点。我认为，指定那些应该在函数签名中清晰明了的细节的冗长注释是一个坏主意，这并没有什么“不合理”的。在您的示例中，唯一应该在注释中出现的部分是@brief。参数和返回值应该从查看函数签名中直接明显。我的态度是非常合理的，你的呢？ - jalf

@Jalf，不，不，不是的。你是对的。是我错了。你提出了一个非常公正的论点，并且以礼貌的方式表达（“如果你想写一本小说，至少请为用户考虑一下，将其放在单独的文本文件中，而不是代码中”）。顺便说一句，这也是自动文档格式从一开始就被开发的原因之一：为了避免单独的文本文件没有人愿意阅读。 - Baltasarq

我认为问题在于这只是给你一些没有人费心编写的文档。;) - jalf

Answer 6

如果您使用Doxygen，它将从头文件和实现文件中生成文档，但如果文档同时出现在头文件和实现文件中，则头文件优先，因此避免重复并在头文件中记录文档。另外，头文件定义了用户接口，这是类的用户感兴趣的内容。此外，如果您将代码部署为库或对象代码，则用户只能访问头文件。

- Clifford