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

Question

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

Answer 1

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

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

Answer 2

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

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

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

我们是否在Core项目中的模型中一直向下开始，并通过基础架构，DataAccess服务和存储库以及用户界面进行操作？ 是

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

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

Answer 3

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