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 回答