注释接口、实现或两者？

我想我们所有人(当我们可以被打扰的时候)都会注释我们的接口。

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
/// <summary>
/// Will 'bar'
/// </summary>
/// <param name="wibble">Wibble factor</param>
void Bar(string wibble);
}

您是否还对实现进行了评论(也可以提供给客户端，例如作为库的一部分) ？如果是这样，你如何保持两者的同步？或者你只是添加一个“查看文档界面”的注释？

谢谢

45540 次浏览
小开

如果您使用 GhostDoc加载项，当您右键单击并在方法上选择“ DocumentThis”时，它将使用接口中的注释更新实现。

小开

注释接口应该有足够的文档来弄清楚如何使用实际的实现。我唯一要在实现中添加注释的情况是，它是否有为满足接口而插入的私有函数，但这些注释只是内部注释，不会出现在在线文档中或客户端可用的文档中。

实现就是这样，只要它们符合接口，就没有必要分别记录它们。

小开

只有接口。注释两者都是重复的，如果代码发生变化，这两组注释很可能最终会失去同步。用“实现 MyInterface”对实现进行注释... ... 像 Doxy之类的东西将生成文档，其中包括派生的文档到实现的文档中(如果设置正确的话)。

小开

对于 C # ，它取决于 IMO: 如果您使用显式接口实现，那么我不会对实现进行文档化。

但是，如果您直接实现接口并使用对象公开接口的成员，那么也必须对这些方法进行文档化。

正如 Nath 所说，您可以使用 GhostDoc 自动将接口的文档插入到实现中。我将 Document This 命令映射到 Ctrl + Shift + D 快捷方式，它是我几乎自动按下的键之一。我相信 ReSharper 还可以在为您实现方法时插入接口的文档。

小开

我们只需要注释接口，注释很容易与派生类或基类/接口不同步，所以把注释放在一个地方很好。

虽然它看起来像@Nath 可能建议一个自动化的文档工具，帮助保持东西在一起(听起来很酷，如果你使用它)。在这里，WhereIWorkAndYouDontCare 的注释是针对开发人员的，因此在代码中只有一个位置是首选的

小开
最佳答案

作为一般规则，我使用与代码相同的 DRY (不要重复自己)原则:

  • 在接口上，记录接口
  • 在实施时，记录实施细节

Java 特定的 : 在记录实现时，使用{@Heritage itDoc }标记从接口“包含”javadocs。

了解更多信息:

小开

我创建了一个工具，可以对 XML 文档文件进行后处理，以添加对 < Heritage itdoc/> 标记的支持。

虽然它对源代码中的智能感知没有帮助，但是它允许修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中使用智能感知。

这是在 www.inheritdoc.io (免费版本)。

小开

您当然可以同时注释这两个内容，但是如前所述，您会遇到同时维护这两个内容的问题。然而，在这个时代，任何消费代码真的不会使用 IoC/DI 和不使用接口吗？考虑到这一点，如果你只想麻烦注释一个，我强烈建议注释接口。这样，代码的使用者将更有可能获得良好的智能感知提示。

小开

C # 用法:

接口可以是这样的:

    /// <summary>
/// Helper class to access various properties for the current site.
/// </summary>
public interface ISiteHelper
{
/// <summary>
/// Gets the site id of the current site
/// </summary>
/// <returns>The site id.</returns>
int GetSiteID();
}
}

实现可以是这样的:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
/// <inheritdoc />
public int GetSiteID()
{
return CommonRepository.GetSiteID();
}
}

提交答案