C++ 在实现文件中包含注释类声明

每个人都知道可读性更强的代码的优点。因此，为了使我的代码更具可读性，我通常会在该类的实现文件中包含带注释的类声明。
通过这种方式，我无需浏览各种包含目录即可进入定义。
那么，这是一个好的实践还是仅仅是一个文档 如果有一些标准技术，请告诉我。
编辑：
有没有办法从Vim中的实现迁移到类声明？
除了在新的缓冲区中打开它

---

谢谢

这没有多大帮助，因为当类定义大于一个屏幕时，您的同事将不得不向上滚动以获得声明。 现代IDE在定位声明方面非常好，因此这是无用的

有时候，唯一真正重要的事情是您将访问标识符 定义函数时在注释中。这确实为试图理解代码的人节省了时间

这样就足够了：

//private
void Car::ReplaceDriver(const std::string & NewDriver)
{

}

---

这实际上是适得其反的，因为在修改类声明时，现在必须更改三个位置而不是两个位置，并且编译器不会检查其中一个位置以捕获任何不匹配

此外，在大型和快速发展的项目中，注释总是过时的，因此它们不能被信任

所有现代IDE都可以通过多种方式从类实现中访问类声明，所有这些方式都比滚动到文件顶部然后再返回更方便

---

作为替代，考虑使用一个自动文档工具，如。可以告诉Doxygen在文档中包含整个类声明——包括语法突出显示、行号和到源文件的链接。您可以在构建过程中包含一个doxGePASS，并且总是有一个最新的代码引用。

< P>我会考虑文档，并且从未在其他地方看到过。当修改类时，注释将很快失去同步（或者在那里查看您永远无法确定）

不确定您使用什么环境，但在查找声明时，我通常使用编辑器的功能（在Mac Xcode和Windows VisualStudio上，您可以右键单击某个内容，然后跳转到其定义或声明）.

这违反了原则：更改声明时必须保留注释

阅读你的代码也没有多大帮助

正如他们（从记忆中）所说：“如果代码和注释讲述了不同的故事，那么它们肯定都是错的。”

有帮助的是：

• 确保标题中的类声明有很好的文档记录和/或非常清楚类的用法：这是大多数类用户首先查看的地方，因为这是类的“手册”（无论是注释还是显式函数）
• 写这些评论的方式要告诉你的意图，而不是它将要做什么：意图是它应该做什么，而不是它做什么（如果它有问题）——这样你就可以给其他人（或你自己）提供线索来修复实现中的错误，因为他们可以理解你试图做什么
• 不要在您的定义文件（cpp）中报告标题注释，因为它将是重要的
• 在定义代码中写下您需要告知意图的注释，以及您所做的可能不明显的注释
• 如果可能，将实现代码中的注释替换为实代码（函数或类）：您通常可以用显式名称将代码块封装在函数中，或将操作结果封装在显式名称的变量中——程序员会更多地插入执行的代码而不是不清楚的注释

---

哦，是的。。我明白你的意思。。即使许多编辑器都提供了段折叠，那么长的注释一开始看起来可能是无用的和混乱的。如果你的编辑器提供了段折叠，它通常还提供了定位声明的功能。坏主意：大多数好的编辑器允许你在几次击键后从声明切换到定义。检查VIM和Emacs的标签文件，检查你的FoviGUI IDE的选项。C++通过要求分割头/源来破坏干式原理…我不这么认为：声明和定义显然是不同的信息（它们相互补充）。问题是，要为它的声明和定义标识某些内容，您必须至少重新键入它的声明。如果有一种方法可以简单地使用声明中使用的名称，那么它看起来就不那么像一个干涸的休息。