我想我们所有人（当我们被打扰时！）评论我们的界面。例如
/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
/// <summary>
/// Will 'bar'
/// </summary>
/// <param name="wibble">Wibble factor</param>
void Bar(string wibble);
}
您是否还评论了实现（也可以提供给客户，例如作为库的一部分）？如果是这样，您如何管理使两者保持同步？还是您只是添加“查看文档界面”评论？
谢谢
【问题讨论】：
标签： c# java comments interface
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();
}
}
【讨论】：
InheritDoc 将显示Object 的文档。
您当然可以同时评论两者，但是您会遇到维护两者的问题（如前所述）。然而，在这个时代，任何消费代码真的不会使用 IoC/DI 并且不使用接口吗？鉴于此，如果您只想打扰评论一个，我强烈建议您评论界面。这样，您的代码的使用者很可能会得到很好的智能提示。
【讨论】：
我创建了一个对 XML 文档文件进行后处理以添加对
虽然它对源代码中的 Intellisense 没有帮助，但它确实允许将修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中与 Intellisense 一起使用。
位于 www.inheritdoc.io（提供免费版本）。
【讨论】：
作为一般规则，我使用与代码相同的 DRY（不要重复自己）原则：
Java 特定：在记录实现时，使用 {@inheritDoc} 标签从接口中“包含”javadocs。
更多信息：
【讨论】：
<inheritdoc />，SandCastle 支持。 (More info...)
inheritdoc 页面提供的链接 @Virtlink 的更新版本：ewsoftware.github.io/XMLCommentsGuide/html/…
我们只是对接口进行注释，cmets 很容易与派生类或基类/接口不同步，将它放在一个地方真是太好了。
虽然看起来@Nath 可能会建议使用自动化文档工具来帮助将事物保持在一起（如果您使用它，听起来很酷）。在 WhereIWorkAndYouDontCare 中，cmets 用于开发，因此首选代码中的单个位置
【讨论】：
对于 C#，这取决于 IMO：如果您使用显式接口实现，那么我不会记录实现。
但是，如果您直接实现接口并将接口的成员与您的对象一起公开，那么这些方法也必须记录在案。
正如 Nath 所说，您可以使用 GhostDoc 将接口的文档自动插入到实现中。我将 Document This 命令映射到 Ctrl+Shift+D 快捷方式，它是我几乎自动按下的击键之一。我相信 ReSharper 还可以选择在为您实现方法时插入接口的文档。
【讨论】：
只有界面。评论两者是重复的，如果代码发生变化，这两组 cmets 最终可能会不同步。用“implements MyInterface”评论实现......像 Doxygen 这样的东西会生成包含派生文档到实现文档中的文档（如果您正确设置它们）。
【讨论】：
注释接口应该是足够的文档来弄清楚如何使用实际的实现。我将 cmets 添加到实现中的唯一一次是它是否具有插入以满足接口的私有函数，但是它们将是仅限内部的 cmets，并且不会在在线文档中看到或对客户可用。
实现就是这样，只要符合接口就不需要单独记录。
【讨论】：
如果您使用GhostDoc 插件，它会在您右键单击并在方法上选择“记录此”时使用界面中的注释更新实现。
【讨论】：