您应该对私有方法进行XML评论吗？

Question

所以我在我的代码中使用XML注释来帮助解释公共方法和公共成员,另一位开发人员提到我并不是所有的方法都有XML注释.我使用规则,如果是公共的或受保护的,添加XML注释,如果是私有的,则不要.

这听起来合乎逻辑,还是有理由将XML注释为私有方法？

Answer 1

关于评论没有强有力的规则,但我认为评论公共/内部/受保护的方法是好的.

有时我会在不清楚时评论私有方法.理想情况下,代码应该是自我记录的.例如,如果您有类似的方法

Item GetItemByTitle(string title)

然后不需要写评论,因为它足够清楚.但是如果某个方法对于其他开发人员来说可能不清楚,请将您的注释或重命名/重构方法事件(如果它是私有的).我个人更喜欢阅读代码,而不是评论:)如果你有太多的评论代码变得难以阅读.我的规则是仅在需要时才使用注释.

如果在您的项目中,您可以方便地记录所有方法,包括私有方法,那么请遵循此规则.

Answer 2

对私人和受保护成员发表评论也是有意义的 - 可能的原因包括:

• 另一个开发人员可能需要使用代码,并且一致的评论方法可以证明是有帮助的;
• 您可能希望在某个时刻自动生成源代码的帮助/文档文件; 在这种情况下,缺少Visual Studio XML注释可能会导致大量未记录的代码.

我并没有真正理解为什么要将XML注释限制为公共成员.