对接口、实现或两者都进行注释?

作为一般规则,我使用与代码相同的干燥(不要重复)原则:

• 在接口上,记录接口
• 关于实施,记录实施细节

特定于Java的 :在记录实现时,使用@inheritDoc标记从接口“包括”javadocs。

更多信息:

• Official javadoc documentation
• 一些非官方的 advice .

如果您使用 GhostDoc 另外,当您右键单击并在方法上选择“document this”时,它会用界面上的注释更新实现。

对于C它依赖于IMO:如果您使用显式接口实现,那么我不会记录实现。

但是,如果您直接实现接口并用对象公开接口的成员,那么这些方法也必须记录下来。

正如Nath所说,您可以使用ghostDoc自动将接口的文档插入到实现中。我把这个命令的文档映射到ctrl+shift+d快捷键,它是我几乎自动按下的一个按键。我相信Resharper在为您实现方法时,还可以选择插入接口的文档。

我们只是对接口进行注释,注释很容易与派生类或基类/接口不同步,因此只在一个地方放置它是很好的。

虽然看起来@nath可能会建议使用一个自动化文档工具来帮助将事情保持在一起(如果使用它,听起来很酷)。在这里,我的工作和您不需要的注释都是针对dev的,所以代码中最好有一个单独的位置。

仅接口。注释两者都是重复的,如果代码发生更改,这两组注释可能最终会失去同步。用“implements myinterface”注释实现…像doxygen这样的东西将生成文档,这些文档将派生的文档包含到文档中以供实现(如果设置正确)。

注释接口应该有足够的文档来了解如何使用实际的实现。我将向实现添加注释的唯一时间是,如果它具有为满足接口而插入的私有函数,那么它们将是仅内部注释,并且不会在联机文档中看到,也不会提供给客户机。

实现就是这样,只要它们符合接口,就不需要单独记录它们。

我创建了一个工具,用于后期处理XML文档文件,以添加对<inheritDoc/>标记的支持。

虽然它对源代码中的intellisense没有帮助,但它允许修改后的XML文档文件包含在nuget包中,因此在引用的nuget包中使用intellisense。

位于www.inheritDoc.io(免费版本)。