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>标记（see MSDN）。这样，您只需编写一次注释，但可以将其作为文档包含在多个不同的位置（例如，声明和接口的实现）。

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

Answer 2

更愿意发表评论。请记住，接口方法定义应包含消费者实现或调用它所需的所有信息。该实现与消费者相关，并且与选择使用哪一个相关，因此也应该适当评论。

最重要的是要更清晰而不是更少。

Answer 3

记录您的界面。

如果您的实施更一般或更具体，例如可以使用更广泛的输入或返回或抛出更具体的输出，然后记录实现。

如果实现与界面没有区别，那么您可以使用<inheritdoc />。

您应该为Interfaces，具体实现或两者编写XML注释吗？

3 个答案: