使用C＃Intellisense注释的最佳实践

Question

我们有一个Visual Studio 2010解决方案，其中包含几个符合Jeffery Palermo的洋葱架构模式（http://jeffreypalermo.com/blog/the-onion-architecture-part-1/）的C＃项目。我们想使用三条斜线添加Visual Studio Intellisense评论，但我们希望看看是否有人知道有多远的最佳实践。我们是否在Core项目中的模型中一直向下开始，并通过基础架构，DataAccess服务和存储库以及用户界面进行操作？或者以更有限的方式使用这些评论更好，如果是这样，将Intellisense评论应用于哪些重要对象？

Answer 1

将它们添加到公共API中公开的任何方法，这样您就可以为调用者提供使用外部接口时所需的所有信息。例如，该方法可能抛出哪些异常和其他评论。

将这些类型的注释添加到私有方法仍然是有益的，我仍然这样做是为了保持一致。如果您计划从评论中生成文档，这也会有所帮助。

Answer 2

虽然从技术上讲，存在太多文档，但99.99999％的时间不适用此例外。

尽可能多地记录所有内容。正式的，非正式的，思想流。每一条评论都会帮助一些继承你的代码或者必须与之交互的穷人。

（这就像旧规则“错误可能在编译器中，而不是你的代码。编译器也有错误。这不是那个时代之一。”）

我们是否一直在Core项目的Model中开始，然后通过Infrastructure，DataAccess服务和存储库以及用户界面进行操作？的是

或者以更有限的方式使用这些评论更好，如果是这样，将Intellisense评论应用于哪些重要对象？ 如果你愿意的话。将它们应用于您编写的任何函数，而不是VS自动生成

我看过有限的“intellisense”评论......但随后是广泛的代码内评论。只要“内容”存在，生活就会好。我通常在intellisense评论中包含关于每个函数的简短模糊，但是在函数和死树文档中放置了大部分“这就是我这样做的原因”。

Answer 3

我同意弗莱彻的观点。从面向公众的类和方法开始，然后逐步进入私有代码。如果您从头开始，我强烈建议您为自己的方便将XML注释添加到所有代码中，但在这种情况下，从公共方法开始，然后在您进行更新时更新其他类是一个很好的解决方案。