你应该为接口、具体实现还是两者都写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>。

这是一种好的注释实践方法吗？还是有其他不同的方式？我只需跳过接口的注释吗？

- Chev

---

可能是接口、实现或两者都注释？的重复问题。 - Yuriy Faktorovich

Answer 1

您可以将注释定义在单独的文件中，然后使用<include>标签（请参阅MSDN）。这样一来，您只需编写一次注释，就可以将其作为文档包含在多个不同的位置（例如接口声明和实现）中。

当然，这需要更多的纪律性，因为它更难写。而且它也有点不太有用，因为您看不到它们在源代码中。但是，如果您想使用XML注释构建文档，则这可能是一个不错的方法。

- Tomas Petricek

---

（我没有在“可能的重复”答案中看到这个，所以我在这里发布它，因为它是特定于C#的答案） - Tomas Petricek

我之前不知道 <include> 标签。谢谢。如果可以的话，我想在实现类中包含更详细的注释，在接口中包含通用的注释（就像我在问题中举的例子）。我并不认为这是重复自己，正如你所说的，它在源代码中很容易阅读。然而，我非常喜欢这个方法，将来可能会在其他项目中用到。 - Chev

+1，但作为一个不喜欢评论的人来说，这似乎是个更糟糕的主意。我最大的问题在于评论可能会掩盖功能，特别是当它们变得过时时。这创造了额外的抽象层，使其更难以保持更新。 - Yuriy Faktorovich

在我最初提出这个问题的三年里，我已经理解了@YuriyFaktorovich所说的内容。如果您随着代码更改及时更新评论，那么它们才具有附加价值。我回到旧代码并注意到随着代码更改，许多评论已经过时。您会对它们的存在感到厌倦，并且有点忘记它们的存在。 - Chev

抱歉，但那没有意义。注释不应该冗长。如果您正在编写注释并且它变得“过时”，则您的注释可能过于详细或者您的方法命名/实现不当。方法注释不应该过时，因为该方法应该1）具有接口，并且2）一直执行相同的操作。如果它确实在执行不同的操作，请编写一个新方法。 - Robert Noack

注释会随着代码的更改而过时，即使您遵循了所有规定。好的注释概述了方法的接受参数和返回值。当有人添加/更改/删除方法的参数并且没有更新注释时，这是对方法的完全有效的更改，不需要新方法，现在注释已经过时了，因为懒惰。我甚至没有反对注释，我只是说我理解Yuriy的观点。仅仅因为一个方法执行了相同的操作，并不意味着接口从未得到更新... - Chev

Answer 2

建议都加上注释。记住，接口方法定义应包含消费者需要实现或调用它的所有信息。实现对于消费者来说也很重要，因为他们需要选择使用哪个，所以应该适当地加上注释。

总之，应该偏向于更多的清晰度而不是少。

- btt

Answer 3

记录你的接口。

如果你的实现更通用或更具体，例如可以处理更广泛的输入或返回更具体的输出，则在实现上记录下来。

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

相关：如何在C#中继承文档？

- Danny Varod