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

在包含转发声明的头文件中，还是在包含实现的.cpp文件中，像这样

//header.h
/* About foo() */
void foo();
/* About bar() */
int bar();
/* About A */
class A
{
public:
    /* About A's constructor */
    A();
    ....
}

或

---

对于用法信息，最好放在标题中。那是人们首先看的地方

---

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

如果你使用的是某种自动文档生成器，注释应该放在它告诉你应该放在哪里的地方

否则，我会在函数定义而不是函数声明的旁边添加常规的“thisfunction does X”注释（当然，除非函数是在其定义处声明的）

---

由于函数声明可能有点笨重，将文档放在头文件中通常会使一次查看与给定类相关的所有注释变得更容易，从而提高其他开发人员对该类的一眼理解。

如果使用Doxygen，它将从，但是，如果文档同时出现在头部和实现中，则头部将优先，因此避免重复并记录头部

标题还定义了类用户感兴趣的用户界面。此外，如果将代码作为库或对象代码部署，则头是用户唯一可以访问的源。C++的

< P>，我将“文档注释”放在CPP和H.

中。 cpp包含代码，并且在描述它们的每个主要代码元素（类、方法等）上都有文档注释-通常使用doxygen或文档XML注释格式（虽然我不倾向于生成外部文档，但我发现坚持标准化格式非常有用，如果/当我决定需要时，可以将其提取到外部工具）。这是一份全面的文档，它准确地解释了调用者应该如何使用方法，以及任何想要修改代码的人都需要理解的设计细节，以便他们理解“契约”的意图，以及关于代码操作需要理解的任何重要内容。（我已经为VisualStudio编写了一个加载项，它使创建和更新这些评论变得快速而简单，因此，要始终如一、全面地记录这样的内容，实际上不需要太多努力）

---

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

您应该将注释放在文件声明中，即在头文件或接口文件的一端使用.h扩展名初始化

可能，对于分发版，您将直接发送头文件，而.cpp文件是二进制格式的，即不可读，因此如果您希望有人阅读您的注释，它们应该在头文件中

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

---

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

+1。如果您在非开放许可证中分发库或其他内容，则只需将代码文档与hea一起分发即可如果我不必检查标题，文档就非常成功。注释没有被编译！没有，但是修改它们会强制重新编译。你知道，有些人会定义函数

int power（int base，int exponent）；

。然后你可以在不删除任何信息的情况下删除6行评论。我可能可以同时在屏幕上显示两个以上的功能。如果你想写小说，至少帮用户一个忙，把它放在一个单独的文本文件中，而不是放在代码中。这只是一个简单的示例。创建示例是为了故意表现得很明显。你的态度是不合理的。不合理？这是一个有趣的观点。我没有看到任何“不合理”的东西如果说详细的注释主要指定了函数签名中应该清楚的内容，这是一个坏主意。在您的示例中，注释中唯一属于

@brief

部分。从函数签名看，参数和返回值应该是显而易见的。我的态度是非常合理的。您的s？@Jalf，不，不，不是。你是对的。错的是我。你以礼貌的态度进行了非常公平的辩论（“如果你想写小说，至少帮用户一个忙，把它放在单独的文本文件中，而不是代码中”）.顺便说一句，这就是为什么从第一次开发自动文档格式的原因之一：为了避免没有人愿意阅读单独的文本文件。我认为问题在于，这反而会提供没有人愿意编写的文档。；）例如：“当然，除非函数在其定义中声明”…在这种情况下，您不将它放在函数定义旁边？那么您将它放在哪里？；）

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