你应该在私有方法上编写XML注释吗？

Question

因此，我在我的代码中使用XML注释来帮助解释公共方法和公共成员。另一位开发人员提到我的部分方法没有XML注释。我的规则是：如果是public或protected，则添加XML注释；如果是private，则不添加。

这个规则听起来合理吗？或者有什么原因需要对私有方法添加XML注释吗？

- Rodders

---

无论访问修饰符如何，我个人都会尝试对我的所有方法进行注释。通常私有方法执行更重要的操作，如果需要进行更改，则很可能需要去这个地方。你写注释不仅是为了使用你类的人，也是为了自己。 - Andrei V

Answer 1

关于注释并没有严格的规定，但我认为注释公共/内部/受保护方法是好的。有时候当私有方法不太清晰时，我也会对其进行注释。理想情况下，代码应该是自我描述的。例如，如果您有一个像

Item GetItemByTitle(string title)

如果一个方法的意义非常清晰，不需要写注释。但是，如果这个方法可能对其他开发人员不够清晰，请添加注释或者重命名/重构这个方法，即使它是私有的。个人而言，我更喜欢阅读代码，而不是注释。如果代码中有太多注释，反而会让代码难以理解。我的原则是只在必要时使用注释。

如果你的项目方便记录所有方法，包括私有方法，请遵循这个规则。

- Warlock

---

大家的回答都很好，但我最喜欢这个，有一些非常好的观点。谢谢！ - Rodders

Answer 2

对于私有成员和保护成员进行注释也是有意义的，可能的原因包括：

• 其他开发人员可能需要使用代码，一致的注释方法可以证明有帮助;
• 您可能想要在某个时候自动生成源代码的帮助/文档文件; 在这种情况下，缺少Visual Studio XML注释可能会导致大量未记录的代码。

我真的看不出为什么你会将XML注释限制在公共成员上的好理由。

- w128

Answer 3

我认为一个方法应该足够简单，以至于它的签名就能准确描述它的功能。然而，在处理旧代码时，这并不总是可能的，因此在某些情况下，头注释是有用的，例如：

• 方法的使用不明显（且不能轻易地进行重构）
• 生成API文档

我认为在这里没有硬性规定，如果感觉需要注释，则注释它。

- codemonkeh

Answer 4

我总是把评论所有的方法看作是必要的好习惯，就像有人向我解释时那样，因为如果我对正在发生的事情和原因没有知识，我希望有人向我解释。

我们是一个小团队开发，这确实有助于团队发展。更重要的是，我经常使用自己的注释来弄清楚我三个月前的思路是什么，当我看着一段代码。

将一些有趣的东西添加到你的方法/程序的顶部是绝对值得花时间添加注释的。

- Louis van Tonder

Answer 5

这个问题有点不清晰，您是在问：

1. 通常应该对私有代码进行注释吗？还是 2. 假设您要注释私有代码，您应该使用 XML 还是标准 C# 注释？

是否需要注释

回答第一个问题，需要注释任何代码都有一点“臭味”。当遇到难以阅读且需要解释的代码时，您首先尝试解决的应该是更改（通常是重命名）使代码更易读。使用注释来解释不清楚的方法名称应该是最后的选择。

有一些例外。共享到解决方案之外的 DLL 的公共方法应始终进行注释。

我建议阅读罗伯特·马丁（Uncle Bob）的《Clean Code》书籍，了解更多详细信息。

XML 或 C# 注释

通常情况下，是的，应该使用 XML 注释而不是 C# 注释。 XML 注释会出现在智能感知中。此外，XML 注释与方法绑定，如果您使用重构工具移动方法，XML 注释将与方法一起移动，而 C# 注释很容易与方法分离。

不使用 XML 注释的一个原因是如果您将要公开分发您的 DLL 和 XML 注释文件。 XML 文件将包含所有内部和私有方法的注释。因此，请确保您可以让客户在私有方法上阅读其中任何注释。

- Timothy Klenke