c# - 关于属性最佳实践的 Ndoc？

Question

我的项目经理上周暗示在类中的属性上使用 ndoc。这是应该做的事情吗？这样做是否被认为是最佳实践？我目前正在为我正在处理的项目部分扩展我的所有 ndoc，但不知道我需要多深。我当然已经为类和每个方法提供了摘要、参数、返回和备注，但是属性也需要 ndoc 吗？

Answer 1

就像任何其他成员一样，属性的含义应该被记录下来。这不仅应包括属性的作用或可用于什么，还应包括其初始值、特殊情况（例如，不得分配的值；会导致异常或自动被其他值替换的值），如以及在可能的情况下覆盖派生类中的属性的后果和目的。

Answer 2

公共财产是与外界的合同，我认为它们应该记录在案。

内部属性将仅在同一个程序集中使用，因此您可以不记录它们而侥幸逃脱。

受保护的属性将仅在派生类（内部或公共）中使用，因此它们可能需要一些文档。

私有属性只会在类本身中使用，所以你可以再次摆脱它。

请注意，“逃避不记录它”暗示了我对此的感受：您应该记录。同时我意识到有时你需要做一件事或另一件事......

也许你应该在http://programmers.stackexchange.com上问这个

Answer 3

无论您选择的文档工作流使用 GhostDoc、NDoc 还是其他任何东西，都应该始终记录公共属性。公共属性和方法的 XML 注释会在人们使用时出现在 Intellisence 中，因此没有理由不在那里添加一些东西。即使属性的名称解释了它的作用，也很高兴在那里有 XML 注释来确认这一点。大量代码中有很多陷阱，因此让使用您的代码的人知道他们没有陷入其中是有礼貌的。

私有财产可以去任何一种方式。我会犹豫将其称为特别的最佳实践，因为要查看您必须在课堂上发表的评论，此时您可以简单地查看它的用法。也就是说，我仍然将 XML 注释放在私有属性上，如果不是为了别人，也是为了我自己。从现在起 6 个月后，您将无法记住自己在做什么，并且您可以添加的任何结构性注释都将使您更容易从中断的地方继续学习。