每个人都知道更具可读性的代码的优点。因此,为了使我的代码更具可读性,我通常会在该类的实现文件中包含注释的类声明。
这样我就不必浏览各种包含目录来进行定义。
那么,这是一个好的做法还是只是过度记录?
如果有一些标准技术,请告诉我。
编辑:
有没有办法从 Vim 中的实现迁移到类声明?
除了在新缓冲区中打开它。
谢谢
每个人都知道更具可读性的代码的优点。因此,为了使我的代码更具可读性,我通常会在该类的实现文件中包含注释的类声明。
这样我就不必浏览各种包含目录来进行定义。
那么,这是一个好的做法还是只是过度记录?
如果有一些标准技术,请告诉我。
编辑:
有没有办法从 Vim 中的实现迁移到类声明?
除了在新缓冲区中打开它。
谢谢
这实际上适得其反,因为现在您必须在修改类声明时更改三个位置而不是两个位置,并且编译器不会检查其中一个位置以捕获任何不匹配。
此外,在大型且快速发展的项目中,评论总是会过时,因此它们不可信。
所有现代 IDE 都可以通过多种方式帮助从类实现访问类声明,所有这些都比滚动到文件顶部然后返回更方便。
作为替代方案,请考虑使用自动文档工具,例如doxygen。可以告诉 Doxygen 在文档中包含整个类声明——带有语法高亮、行号和指向源文件的链接。你可以在你的构建过程中包含一个 doxygen pass,并且总是有一个最新的代码参考。
这打破了DRY原则:您必须在更改声明时维护注释。
阅读您的代码也无济于事。
正如他们所说(从记忆中):“如果代码和注释讲述不同的故事,那么它们肯定都是错误的。”
有帮助的是:
这没有多大帮助,因为当类定义大于一个屏幕时,您的同事将不得不向上滚动才能看到声明。现代 IDE 在定位声明方面非常好,所以恕我直言,这是没用的。
有时真正重要的唯一事情是在定义函数时将访问标识符放在注释中。这确实为试图理解代码的人节省了时间。
这样的事情就足够了:
//private
void Car::ReplaceDriver(const std::string & NewDriver)
{
}
我认为它的文档过多,并且从未在其他地方看到过。修改课程时,评论很快就会不同步(或者看那里你永远不确定)。
不确定您使用什么环境,但是在查找声明时,我通常使用编辑器的功能(在 Mac Xcode 和 Windows VisualStudio 上,您可以右键单击某些内容,然后跳转到它的定义或声明)。