NAnt 任务，用于捕获超出范围的源监视器指标

• 下载源代码项目 - 27.15 KB

引言

为了提高我们产出代码的质量，我决定研究一些现成的代码指标工具。我最终选择了 Campwood Software 的 Source Monitor 工具 (Campwood Software)。

第一次在我们现有的代码（大约 260,000 行 CPP 代码）上运行此工具时，我们发现Maximum Complexity（M9）指标达到了 100，而推荐的范围是 [0...10]。由于我们没有时间进行重构，因此决定只关注新开发的部分。但此时第一个问题出现了：

• 如何仅报告新开发代码的指标，而不被一些现有代码引起的超出范围的指标所污染？

此外，我还想

• 自动化指标检查，将其包含到我们的自动构建流程中。
• 在生成的新代码不符合默认推荐规则时发出告警。

先决条件

SMAnalyzer 任务是使用 NAnt 0.85 和 Source Monitor 2.5 开发的。显然，您需要在您的机器上安装这两个工具。

本文介绍的 SMAnalyzer 任务是为了解析 Source Monitor 生成的 XML 文件中的详细信息。您需要自己生成这些文件。请参考 Source Monitor 的在线帮助，它非常清晰。

Source Monitor 实现了检查点的概念，允许您随着时间的推移监控指标。此版本的 SMAnalyzer 不处理 Source Monitor 文件中的多个检查点。它总是使用 XML 结构中找到的第一个检查点。

概念

最初的想法是定义

• 对于新代码：Source Monitor 所有指标的默认阈值。
• 对于遗留代码：用于管理超出默认阈值范围的代码的异常。

该任务仅处理现有的 Source Monitor XML 文件，并使用 XML 格式指定的规则进行检查。

Using the Code

如果您直接使用 NAnt.SMAnalyzerTasks.dll 程序集，只需将其复制到您的 NAnt 安装文件夹的 bin 文件夹中。如果您想重新构建它，请参阅下面的“如何构建任务”部分。一旦 SMAnalyzer 任务准备就绪，您就可以在任何脚本中使用以下简单命令来使用它：

...
 <smanalyzer input=".\sm_details_result.xml" 
	rules=".\threshold_rules.xml" output=".\threshold_results.xml" />
...

input 属性用于指定 Source Monitor XML 详细结果文件。rules 属性用于指定包含检查结果时要应用的规则的 XML 文件。output 属性用于指定检查结果将存储的文件。

阈值规则 XML 语法

用于定义阈值的语法通过以下代码示例进行总结：

<sourcemonitor_thresholds>
  <project version="1.0">
     <project_name>my project</project_name>
     <project_directory>D:\dev\my_project</project_directory>
     <defaults>
        .... 
        <metric id="M9" value=""><threshold min="0" max="10"/>
        ....
     </defaults>
     <customs>
        <files>
           <file file_name="foo1.cpp">
              <metric id="M9" value=""><threshold min="0" max="20" enable="true"/>
		</metric>
              ...
           </file>
           <file file_name="foo2.cpp">
              <metric id="M9" value=""><threshold min="0" max="100" enable="true"/>
		</metric>
              ...
           </file>
           <file file_name="foo3.cpp">
              <metric id="M9" value=""><threshold min="0" max="0" enable="false"/>
		</metric>
           </file>
           ...
        </files>
     </customs>
  </project>
</sourcemonitor_thresholds>

project_name 和 project_directory 标签只是为了提醒您正在处理的 Source Monitor 文件。

两个最有趣的部分是 defaults 和 customs。

• 在 defaults 部分，您可以为每个感兴趣的指标定义一个阈值。这里定义的规则默认应用于项目的每个文件。
• 在 customs 部分，您可以为每个文件上检查的每个指标设置一个例外。此处报告的任何例外都将覆盖默认阈值。您可以完全禁用检查，或者指定另一个范围。

结果文件 XML 语法

所有检查的结果也以 XML 格式保存。下面的骨架总结了报告的信息：

<threshold_results>
  <files>
    <file file_name="foo1.cpp">
      <metric id="M9" value="9"><threshold min="0" max="20" result="good" /></metric>
      <metric id="M13" value="2.29"><threshold min="0" max="10" result="good" /></metric>
    </file>
    ...
    <file file_name="foo4.cpp">
      <metric id="M9" value="12"><threshold min="0" max="10" result="bad" /></metric>
      <metric id="M13" value="2.18"><threshold min="0" max="10" result="good" /></metric>
    </file>
    ...
  </files>
  <project>
    <project_name>my project</project_name>
    <sourcemonitor_version>2.5</sourcemonitor_version>
  </project>
  <statistics>
    <global total_count="71" error_count="4" success_count="67" />
  </statistics>
</threshold_results>

对于每个文件中的每个指标，您将获得检查的最终结果：good 或 bad。为了便于阅读，我们报告了 Source Monitor 计算出的指标 value。在 XML 结构末尾，我们重复了一些 project 信息。我们还提供了一些 statistics 以便快速了解检查结果。

后期处理

由于结果是以 XML 格式生成的，因此它们可以很容易地被其他工具进行额外的分析。在可下载的存档中，您会找到一个 XSL 样式表 (thresholds_results.xsl)，它可以处理结果文件以构建一个 HTML 页面，该页面可以发布到您的 Web 服务器上。
您还可以设想在出现问题时向开发团队发送电子邮件以发出警报等等。

处理遗留代码

如前所述，一个要求是消除由报告为超出范围的遗留代码带来的噪音。
现在可以通过在 rules 文件中定义正确的异常规则轻松实现这一点。
例如，假设文件 foox.cpp 的Maximum Complexity值为40。您可以定义如下异常：

     <customs>
        ...
        <files>
           <file file_name="foox.cpp">
              <metric id="M9" value=""><threshold min="0" max="40" enable="true"/>
		</metric>
              ...
           </file>
        ...
        </files>
     </customs>    

有了这样的规则，该文件将不会被报告为错误，除非在该文件中进行的新开发导致分数恶化。

如何构建任务

NAnt 任务是使用 Visual Studio 2008 SP1 创建的，并且基于 NAnt 版本 0.85。使用了 Framework 2.0。

要构建任务，只需在 Visual Studio 中加载 SMAnalyzer.sln 解决方案即可。
您可能需要添加对 NAnt.Core.dll 的引用，该文件可以在您的 NAnt 安装的 bin 文件夹中找到。
构建完程序集后，只需将其复制到 NAnt bin 目录即可。

改进

1. 截至目前，Source Monitor 的 block_depths 部分不受支持，可以添加。
2. 该任务仅支持第一个 checkpoint。阅读多个 checkpoint 是否有意义？
3. 能够自动生成“关闭”超出范围的遗留代码的异常规则会很好。也许可以使用专用的 XSL？
4. 指标 M8 是一个 string，它被与其他指标一样对待……当作数字……抱歉。

历史

• 2009 年 6 月 12 日：首次发布