我应该在哪里提交文件评论？
在包含forward声明的头文件中，或在包含实现的.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() { ... }
有关使用信息，放入标题更好。 这就是人们首先要看的地方。
如果没有人需要检查你的.cpp文件来确定如何使用这个组件，那么这个文档是非常成功的。
据我所知，每当你改变.h文件中的东西时，就会导致包含该头文件的所有文件都被重新编译。 出于这个原因，我把大部分的评论放在.cpp文件中。
对于C ++，我把“文档注释”放在cpp和h中。
cpp包含代码，并且对每个描述它们的主要代码元素（类，方法等）都有文档注释 – 通常使用doxygen或文档XML注释格式（虽然我不倾向于生成外部文档，但我觉得它很有用坚持一个标准化的格式， 可以提取到外部工具，如果/当我决定我想要的）。 这是全面的文档，可以准确解释调用者应该如何使用一个方法，以及任何想要修改代码的人都需要理解的devise细节，这样他们就能理解“合同”的意图和任何重要的理解关于代码的操作。 （我已经为Visual Studio编写了一个插件， AtomineerUtils ，这使得创build和更新这些评论变得简单快捷，所以实际上没有太多的努力来logging这样的事情）
我的头被视为汇总（编译器和我自己） – 它使用单行//注释，简要介绍每种方法。 这比（有希望相对自我logging的）方法/参数名称给出更多的信息，但比cpp中的详细文档要less得多。 把它看成是一个总结或者提醒，这样可以节省你在实际的实现中获得足够的细节来大部分时间使用这个方法。
如果您正在使用某种自动文档生成器，评论应该在任何地方告诉您应该去的地方。
否则，我把通用的“这个函数做X”注释放在函数定义的旁边，而不是函数声明 （当然，除非函数声明在定义处）。
由于函数声明可能有点笨重，因此将文档放在头文件中通常可以更轻松地一次查看给定类的所有注释，从而使其他开发人员对该类的理解一目了然。
你应该把你的注释放在文件的声明中，也就是在标题或接口文件中，以.h扩展名结尾。
也许，为了发布，你将直接发送头文件和.cpp的二进制forms，即不可读，所以如果你期望有人读你的评论，他们应该在头文件。
还有一些实现文档，在.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);
如果你使用Doxygen，它将会生成文档，但是如果文档出现在头文件和实现文件中，则头文件先行，所以避免重复文件头文件。
此外，头文件定义了用户界面，这是类的用户所感兴趣的。此外，如果您将代码部署为库或目标代码，那么头文件是用户将唯一访问的源文件。
