您应该为接口、具体实现还是两者都写 XML 注释？ [关闭]答案

【问题标题】：Should you write XML comments for Interfaces, concrete implementations, or both? [closed]您应该为接口、具体实现还是两者都写 XML 注释？ [关闭]
【发布时间】：2011-04-05 21:05:08
【问题描述】：

我对应该在哪里应用我的 XML cmets 很感兴趣。我应该在接口中添加更通用的 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>。

这对 cmets 来说是一个好习惯还是有不同的方法？我只是跳过评论界面吗？

【问题讨论】：

Comment the interface, implementation or both? 的可能重复项

标签： c# interface documentation comments xml-comments

【解决方案1】：

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

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

【讨论】：

（我在“可能重复”的答案中没有看到这个，所以我把它贴在这里，因为它是 C# 特定的答案）
我不知道<include> 标签。谢谢你。如果可以同时评论两者，那么我认为我更喜欢在实现类和接口上包含更详细的 cmets（根据我在问题中的示例）。我真的不认为它是在重复自己，正如你所说，它在源代码中是可读的。但是，我非常喜欢这个，并且可能会发现它在其他项目中很有用。
+1，但作为不喜欢 cmets 的人，这似乎是一个更糟糕的主意。我对 cmets 最大的不满是它们会掩盖功能，尤其是过时。这创建了一个额外的抽象级别，使其更难保持最新状态。
自从我最初提出这个问题以来的三年里，我开始理解@YuriyFaktorovich 在说什么。如果您在代码更改时使它们保持最新，注释只是附加值。我回到了遗留代码，并注意到随着代码的变化，不止一些 cmets 已经过时了。你厌倦了他们的存在并忘记了他们。
抱歉，这没有任何意义。评论并不意味着冗长。如果您正在撰写评论并且它“过时”，则要么您的评论过于详细，要么您的方法一开始就命名/实施不当。方法注释不应该过时，因为该方法应该 1) 有一个接口，并且 2) 做它一直在做的同样的事情。如果它真的在做不同的事情，那就写一个新的方法。

【解决方案2】：

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

底线是在更清晰而不是更少方面犯错。

【讨论】：

【解决方案3】：

记录你的接口。

如果您的实现更通用或更具体，例如可以处理更广泛的输入或返回或抛出更具体的输出，然后在实现中记录。

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