应该为接口、具体实现或两者都写XML注释吗?

Question

我对应该在哪里应用XML注释很感兴趣。我是否应该在接口中添加更通用的XML注释，而在实现类中添加更具描述性的注释?这样的:

public interface IObjectRepository
{
    /// <summary>
    ///    Returns an object from the respository that contains the specified ID.
    /// </summary>
    Object GetObject(int Id);
}
public ObjectRepository : IObjectRepository
{
    /// <summary>
    ///    Retrieves an object from the database that contains the specified ID.
    /// </summary>
    public Object GetObject(int Id)
    {
        Object myData = // Get from DB code.
        return myData;
    }
}

为了简单起见，我没有包括<param>。

这是注释的好做法还是有不同的方法?我是否可以跳过对界面的注释?

Answer 1

您可以在单独的文件中定义注释，然后使用<include>标记(参见MSDN)。这样，你可以只写一次注释，但将其作为文档包含在多个不同的地方(例如，一个接口的声明和实现)。

当然，这需要更多的纪律，因为它更难以编写。它也不太有用，因为您不会在源代码中看到它们。但是，如果您想使用XML注释来构建文档，那么这可能是一种很好的方法。

Answer 2

建议同时注释。请记住，接口方法定义应该包含使用者实现或调用它所需的所有信息。实现与消费者相关，也与选择使用哪一个相关，因此注释也应该是合适的。

Answer 3

文档化你的接口

如果你的实现更通用或更具体，例如可以使用更广泛的输入或返回或抛出更具体的输出，那么在实现上记录。

如果实现与接口没有差异，则可以使用<inheritdoc />。

相关:在c#中继承文档?