c# - 您应该为接口、具体实现还是两者都写 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# 中的文档？