所以我在我的代码中使用 XML 注释来帮助解释公共方法和公共成员，另一位开发人员提到并非我的所有方法都有 XML 注释。我使用规则，如果是公共的或受保护的，添加 XML 注释，如果是私有的，则不要。
这听起来合乎逻辑还是有什么理由让 XML Comment 成为私有方法？
问问题
5050 次
5 回答
11
关于评论没有严格的规则，但我相信评论公共/内部/受保护的方法是好的。
有时我会在私有方法不是很清楚时评论它们。理想情况下，代码应该是自我记录的。例如，如果您有类似的方法
Item GetItemByTitle(string title)
那么就不需要写评论了，因为已经很清楚了。但是，如果其他开发人员可能不清楚某个方法，请发表您的评论或重命名/重构方法事件（如果它是私有的）。就我个人而言，我更喜欢阅读代码，而不是评论 :) 如果你有太多评论，代码就会变得难以阅读。我的规则是仅在需要时使用注释。
如果在您的项目中，您可以方便地记录所有方法，包括私有方法，请遵循此规则。
于 2013-10-09T09:50:02.690 回答
8
评论私有成员和受保护成员也是有意义的 - 可能的原因包括：
- 另一个开发人员可能需要使用代码，并且一致的注释方法可能会有所帮助；
- 您可能希望在某个时候自动生成源代码的帮助/文档文件；在这种情况下，缺少 Visual Studio XML 注释会导致大量未记录的代码。
我真的看不出为什么要将 XML 注释限制为公共成员的充分理由。
于 2013-10-09T09:40:43.700 回答
3
我赞同这样的指导理念，即方法应该足够简单，以至于它的签名准确地描述了它的作用。话虽如此，这并不总是可能的（尤其是在使用遗留代码时），因此在某些情况下标题注释很有用。如：
- 使用的方法不明显（不易重构）
- 生成api文档
我不认为这里真的有任何硬性和快速的答案，如果评论它感觉正确，然后评论它
于 2013-10-09T09:52:40.777 回答
3
我总是将我所有的方法评论为一种好习惯，就像必须向某人解释它们一样，因为如果我不知道正在发生的事情和原因，我希望他们向我解释。
我们在一个小团队中发展，这确实有助于团队发展。更重要的是，我经常使用我的 OWN 评论来弄清楚 3 个月前当我查看一段代码时我的思考过程到底是什么。
花一些时间在你的方法/过程的顶部添加一些有趣的东西是绝对值得的。
于 2013-10-09T09:52:48.720 回答
2
这个问题有点不清楚你是否在问：
- 应该对私有代码进行一般评论吗？或者
- 假设您应该使用 XML 还是标准 C# 注释来注释私有代码？
评论与否
要回答第一个问题，需要对任何代码进行注释有点代码异味。当您遇到难以阅读需要解释的代码的情况时，您首先尝试解决的问题应该是更改（通常通过重命名）以使代码更具可读性。使用注释来解释不清楚的方法名称应该是最后的手段。
有一些例外。应始终注释在解决方案之外共享的 DLL 的公共方法。
我建议阅读 Robert C. (Uncle Bob) Martin 的“清洁代码”一书以了解更多详细信息。
XML 或 C# 注释
一般来说，是的，对方法使用 XML 注释，而不是 C# 注释。XML 注释以智能感知方式显示。此外，XML 注释绑定到方法，如果您使用重构工具移动方法，XML 注释将与方法一起带来，而 C# 注释可以很容易地与方法分离。
不使用 XML 注释的一个原因是，如果您将公开分发您的 DLL 和 XML 注释文件。XML 文件将包含所有内部和私有方法的注释。因此，只需确保您对可能阅读任何关于私有方法的评论的客户感到满意。
于 2016-05-05T16:05:18.103 回答