评论界面,实现或两者?

问题

我想我们所有人(当我们可以被打扰时!)评论我们的接口。例如

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

你是否也评论实施(也可能提供给客户,例如作为图书馆的一部分)?如果是这样,你如何管理保持两者同步?或者你只是添加"查看文档界面"评论?

谢谢


#1 热门回答(84 赞)

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

  • 在界面上,记录界面
  • 在实施时,记录实施细节

Java特定:在记录实现时,使用{@inheritDoc}标记从接口"包含"javadocs。

了解更多信息:

  • 官方javadoc文档
  • 一些非正式的建议。

#2 热门回答(6 赞)

如果使用5348214addin,则在右键单击并在方法上选择"Document This"时,它会使用界面中的注释更新实现。


#3 热门回答(4 赞)

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

但是,如果直接实现接口并使用对象公开接口的成员,则必须记录这些方法。

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