SharpDevelop 实践：代码注释
使用开源 IDE 为代码添加注释并查看 FxCop 报告。
引言
如果你还没听说过，SharpDevelop 是一个开源的 .NET IDE，在一定程度上也支持 Mono。在现有的 .NET 开源产品中，SharpDevelop 非常成熟且功能众多。对许多开发者，包括我自己，它正逐渐成为 Visual Studio 的替代品。
背景（或，一些轶事）
言归正传，让我们来谈谈本文的主题。虽然 SharpDevelop 在单个开发者参与时有多种与代码交互的功能，但团队协作场景是专业开发中最常见的。在我工作的公司，我们为 SharpDevelop 和 Visual Studio 开发了多个自定义的应用程序生命周期管理 (ALM) 应用程序和插件，以填补我们独特业务需求的空白。本着 SharpDevelop 的精神，本文介绍其中一个用于开源社区的通用工具。未来还会有更多，敬请期待。
假设你最近运行了 FXCOP，这是微软的一个工具，用于检查你的代码是否符合各种安全、国际化、移动、可移植性和其他模式的规则。FXCOP 会产生大量警告和错误，你需要处理它们来改进你的代码库，但在这里存在一些你无法解决的问题。
首先，尽管该工具以 XML 格式生成警告和错误，并且 SharpDevelop 在 IDE 中报告它们，但你在重新生成项目时会丢失所有这些信息。在 Carbonfrost，我们都有自己的解决办法。有些人过去会打印出几十页的错误消息来修复它们。这有点老套，但我偏爱这种方法，因为我更喜欢纸质记录，用笔记和标记来代替网页和冗长的会议。然而，不久之后，我们公司安装了新的纸张配额，所以那个方法不再可行。其他人则编写脚本和其他构建自动化工具来生成网页和数据库。这一切都相当繁琐，最糟糕的是，它将我们与 IDE 分离，降低了我们的生产力。
其次，即使你拥有错误消息，代码元素也会移动。因此，当你修改代码时，行号很快就会变得毫无用处。将 FXCOP 数据直接关联到源代码比仅仅获取报告要复杂一些。
第三，你如何向你的同事和其他人表明你已经完成了工作？改进代码库的大部分价值在于沟通你如何以及为何进行更改。在 Carbonfrost，我们专门为此构建了一个外部 IDE。这样，我的同事可以使用 Visual Studio，而我可以使用 SharpDevelop，其他人可以使用文本编辑器。我们通过这个辅助 IDE 和一些内部 Web 应用程序进行沟通。
这是任何小型公司都会引以为傲的技术的混合体，因为他们还不想花费高昂的费用购买昂贵的软件。不用说，然而，它与 IDE 的体验非常脱节。编写互操作性代码也非常棘手。因此，为了改进，我着手为 SharpDevelop 编写了一个插件来在一定程度上解决这个问题。本文介绍了我对这个问题的解决方案。我希望这个解决方案至少能起到一定的作用。
比喻与见解
代码 DOM
SharpDevelop 有一个结构良好的 DOM（文档对象模型），用于与代码进行交互，它模拟了你交互的每一个类、方法等。所以，我们从那里开始。DOM 的用处在于它在很大程度上消除了特定于语言的行为，并提供了与源代码交互的结构化模型。这使得重构和其他操作成为可能。在我们的模型中，我们将数据“附加”到 DOM 元素上，因此如果一个类被移动到新的源文件中，数据也会随之附加。正如你现在可以想象的，我们将 FXCOP 的数据纳入了这个附件模型，这使我们能够保留 FXCOP 报告的意义。
注解
当我们向代码元素附加数据时，我们称之为“注解”。注解与代码元素、项目或解决方案相关联，并且注解支持历史记录。例如，你可以更改注解的各种字段并添加新注释，注解历史记录将被持久化。这超出了“TODO”和“FIXME”的代码注释，因为它们与代码是分开的。注解很有用，因为它们在语义上附加到代码 DOM 元素，并且是源代码和项目元数据的一部分。理论上，这意味着数据可以通过其他机制（如 bug 跟踪器）共享，并且即使文件名更改或代码元素重命名，数据也能保持有意义。
使用插件
该插件打包成一个单一文件。该文件实际上是一个简单的 ZIP 文件，包含一个清单文件 *.addin、DLL 和资源。该文件的扩展名为 *.sdaddin。
首先解压本文附带的文件。它包含源代码和 *.sdaddin 文件。如果你已经安装了 SharpDevelop，你应该通过双击桌面上的 *.sdaddin 文件来安装插件。在另一篇关于 SharpDevelop 插件的文章中有对这一点极好的解释。
我们将注解存储在一个名为 <solution-name>.review 的文件中。说实话，这种基于文件的注解存储方案在团队协作时不是最佳选择，但它说明了这一理念。在内部，我们实际上将所有注解存储在 MySQL 数据库中，其他工具会与这些数据进行交互。
实际运行
对于那些只看截图（我承认我有时也是！），这部分是给你们的。没有截图的文章是不完整的，所以它们在这里。我不会花太多时间解释它是如何工作的，但简而言之，这个插件引入了一个新的面板，称为“注解库”。在这里，我们显示每一个注解。有三个按钮用于添加注解、删除注解或导航到已包含注解的元素。
该插件还添加了新的菜单选项。有些被添加到“项目”面板
在“类”面板中也添加了一个类似的菜单。这些项允许你选择一个类或类成员，并为它“添加注解”或“显示已存在的注解”。还有一个命令可以将 FXCOP 输出转换为注解。不过，请先使用内置命令“使用 FXCOP 检查”。
本文开头的插图显示了当你添加注解时会看到的屏幕。这个对话框允许你选择一个任意的“分辨率”和“状态”级别，输入注释，并选择一个任意的代表性图标。
注意事项和未来工作
诚然，“注解库”并不直观，因为你必须通过“类”或“项目”面板来添加注解。我曾考虑过自己实现类浏览器，或者创建一个显示所有带有注解的元素的辅助面板，但这都是一项大工程，并且会重复很多代码。
在带有注解的类和项目的数量上也有一个限制，它们将显示在下拉列表中。我定期以安全的方式保存注解，以防止在环境崩溃时丢失。这应该在一定程度上防止注解文件损坏或部分损坏，或者避免大量数据丢失。备份文件保存在 <solution-name>.review~。将来，我可能会考虑提供 SQL Server 数据库后端而不是文件。
虽然我们支持向命名空间添加注解，但我们无法做到这一点，因为类浏览器不公开命名空间的菜单。目前，还有一个 hack 来让“注解库”与类浏览器进行交互。用于使画廊的某些部分与类浏览器工作的代码也是 hack，所以我认为如果类浏览器发生变化，它可能无法很好地兼容。我也没在 SharpDevelop“Montferrer”上测试过。在 CodePlex 上的 SharpDevelop+Community 网站上，你会发现有无数扩展它的机会。
走出沙盒，登上舞台
整个插件——源代码、测试、文档和本文——大约在五天内完成。这是在我日常的常规工作之外完成的，所以除了 hack 和变通方法之外，过程相当轻松。这也是我的第一篇 CodeProject 文章，所以整个经历相当有趣，而且比我预期的要短得多。
这个插件及其未来版本将在我们称之为 SharpDevelop+Community 的项目中发布，该项目是一系列旨在增强 SharpDevelop 的开源项目。如果你有兴趣，请访问我们的网站！我们正在开发几个插件来为这个项目做贡献。在后续的文章中，我将介绍它们。如果不行，发行版中一定会包含足够（虽然可能没那么有趣）的文档。
致谢
在这个插件的艺术、法律、文案编辑和网站素材方面，我得到了一些人的帮助。你们的辛勤工作非常值得感激！
历史
- 版本 1. 2007 年 6 月 3 日。原始贡献
- 2007 年 6 月 22 日。文章经过编辑并移至 CodeProject.com 的主文章库