0

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

谢谢

4

4 回答 4

7

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

此外，在大型且快速发展的项目中，评论总是会过时，因此它们不可信。

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

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

于 2009-11-17T17:59:12.163 回答
3

这打破了DRY原则：您必须在更改声明时维护注释。

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

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

有帮助的是：

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

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

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

这样的事情就足够了：

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

}
于 2009-11-17T17:44:42.380 回答
1

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

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

于 2009-11-17T18:08:41.103 回答