在实现文件中包含注释的类声明答案

【问题标题】：Including commented Class declaration in implementation file在实现文件中包含注释的类声明
【发布时间】：2010-12-17 13:20:29
【问题描述】：

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

谢谢

【问题讨论】：

坏主意：大多数优秀的编辑器允许您在几次击键中从声明切换到定义。检查 vim 和 emacs 的标签文件，并检查您最喜欢的 GUI IDE 上的选项。

标签： c++ documentation comments code-readability

【解决方案1】：

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

此外，在大型且快速发展的项目中，cmets 总是会过时，因此无法信任。

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

作为替代方案，请考虑使用自动文档工具，例如 doxygen。可以告诉 Doxygen 在文档中包含整个类声明——带有语法高亮、行号和指向源文件的链接。您可以在构建过程中包含一个 doxygen 通道，并且始终拥有最新的代码参考。

【讨论】：

【解决方案2】：

这违反了DRY 原则：您必须在更改声明时维护 cmets。

而且阅读您的代码也无济于事。

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

有帮助的是：

确保标题中的类声明有据可查和/或非常清楚类的用法：这是类的大多数用户首先会看到的地方，因为那是类的“手册”（无论是 cmets 还是显式函数）；
以一种说明你的意图的方式编写这些 cmets，而不是它会做什么：意图是它应该做什么，而不是它做什么（如果它有问题）——这样你就可以为其他人提供线索人们（或您以后）来修复您的实施中的错误，因为他们可以理解您尝试做的事情；
不要在你的定义文件中报告你的头文件 (cpp)，因为它是多余的！
在定义代码中写出你需要说明意图的地方以及你所做的可能不明显的地方；
如果可能，将实现代码中的 cmets 替换为真实代码（函数或类）：您通常可以将代码块封装在具有显式名称的函数中，或者将操作结果封装在具有显式名称的变量中名称 -- 程序员会比不清楚的 cmets 更倾向于执行代码......

【讨论】：

C++ 打破了 DRY 原则，要求拆分头/源...嗅探
我不这么认为：声明和定义显然是不同的信息（相互补充）。问题是要为它的声明和它的定义识别一些东西，你必须至少重新输入它的声明。如果有一种方法可以简单地使用声明中使用的名称，那么它看起来就不那么像 DRY 中断了。

【解决方案3】：

这并没有太大帮助，因为当类定义大于一个屏幕时，您的同事将不得不向上滚动才能看到声明。现代 IDE 在定位声明方面非常好，所以恕我直言，这是没用的。

有时真正重要的是你把访问标识符在定义函数时的注释中。这确实为试图理解代码的人节省了时间。

这样就够了：

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

}

【讨论】：

哦，是的..我明白你的意思了..即使许多编辑器提供分段折叠，这么长的评论乍一看似乎无用且令人困惑
是的，如果你的编辑器提供段折叠，它通常也提供定位声明。

【解决方案4】：

我认为它的文档过多，并且从未在其他地方看到过。修改类时，cmets 很快就会不同步（或者看那里你永远不确定）。

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

【讨论】：