Ndoc on properties的最佳实践？

Question

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

Answer 1

公共财产是一种对外契约，我认为它们应该被记录下来。

内部属性将仅在同一程序集中使用，因此您可以不对其进行文档记录。

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

私有属性将只在类本身中使用，因此，同样，您可以使用它。

请注意，“不记录它就能脱身”建议了我对此的看法:你应该记录下来。同时，我意识到有时你需要做一件事或另一件事...

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

Answer 2

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

Answer 3

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

私有属性可以选择任何一种方式。我不愿称它为一种特殊的最佳实践，因为要查看您必须在类中的注释，您可以只查看它的用法。也就是说，我仍然将XML注释放在私有属性上，如果不是为了其他人，那就是为了我自己。你不可能记住6个月后你在做什么，你可以添加的任何结构注释都会让你更容易从你停止的地方继续。