sonarqube官方文档翻译之UserGuide

#SonarQube#

---

今天继续学习使用SonarQube分析项目代码，为了便于理解，将官方手册用到的翻译出来。

UserGuide

Quality Gate

Use the Best Quality Gate Configuration

推荐默认配置，对于每一个版本，我们都会根据SonarQube的能力调整默认质量门（Quality Gate）。SonarQube6.2版本新增了三个度量，可靠比，安全比，可维护性比。极力推荐这些新的度量作为默认质量检查的一部分。
注意质量门的条件，必须使用不同的值。举例说明，对于检查绝对数量值没有意义，如：代码行数大于1000.

Quality Gate Status

在Project页面上方会显示质量门现有的状态。
若质量门显示状态为“Fails”，你可以注意到是哪些地方出了问题，也可以为你的其他感兴趣的项目提交新的质量门状态。

Security

质量门可以被任何用户访问。若想要改变质量门配置，必须获得管理员允许。项目管理员可以选择哪个项目和哪个质量门关联。

Define Quality Gate

每个质量门条件是有以下部分组合：

• 度量（measure）
• 时间（period）：值（对于时间）或漏洞（不同值）
• 比较操作符
• 警告值（可选）
• 错误值（可选）

例如，条件组合可能为：

• measure：Blocker issue
• period:Value
• comparison operator:>
• error value:0
  可以简单表述为：没有致命问题。

---

Projects

“项目”这一栏可以对多个项目进行查看度量。
登录的用户可以查看默认的喜欢的项目，如果你没有选择最喜欢的项目，你可以看到所有你有权限访问的项目。有以下过滤标准：

• 失败质量门
• 低可靠性，安全性和可维护性
• 低覆盖率
• 过多的重复代码

一旦你选择了你的项目，你就可以查看项目更多的细节->Projects

---

Local and Branch Analysis

• 提交代码之前检查代码问题–SonarLint。在你的IDE中提出问题。
• 合并pull request之前检查代码问题–PR分析允许你配置你的CI引擎来执行“预演”分析。新的问题都会标注出来。如果没有新问题，则会提示“all clear”消息。在 GitHub plugin（插件）支持 GitHub项目的PR分析，或者其他的插件。
• 在SonarQube中分析长期的分支–这种情况下，在SonarQube中持续分析典型项目，可以称为主分支，包括SonarQube中正在分析的第二分支。典型的项目是版本分支。在这种场景下，可以通过添加sonar.branch=[branch key]分支分析版本分支的属性，在SonarQube中创建一个第二的，独立的项目。

---

Code Viewer

SonarQube的核心是代码审查，它展示了代码源文件和高层次的数据：

• 行数
• 问题数
• 单元覆盖率
• 重复度
• SCM信息（近期提交某行代码的人和时间）
• 给定测试文件的测试结果，执行时间和状态

code viewer有两个方面：现有的文件，标记的文件

现有文件

布局包括两个部分：
头部位于文件的上方。展示了有用的信息，提供了修饰和过滤动作。
源代码居中，基于头部选择显示额外的信息。
具体见官网文档说明。

Coverage

• 红色：表示没有被覆盖
• 橙色：表示部分被覆盖
• 绿色：表示完全覆盖

对于Java程序，使用JaCoCo，可以得到以下信息：
- 显示覆盖特定一行不同测试的数量；
- 列出这些测试；
- 能够寻找定义这些测试的测试文件。

Duplications

通过点击相应位置，展开查看重复代码行数，定位重复代码位置。

Tests

在测试文件上，构件视图可以看到不同的数据。
在“Show details”选项提供了“coverage per test（每个测试单元的覆盖率）”信息。

这一部分可以回答两个问题：
- 哪一个文件被给定的单元测试覆盖？
- 有多少代码行数被给定的单元测试覆盖？

---

Issues

每个issue有五个等级：
1. BLOCKER:会影响应用程序的缺陷：内存泄漏，未关闭的JDBC连接…必须立刻修复的代码；
2. CRITICAL ：可能会影响应用程序的缺陷或者是安全性缺陷：空的catch块，sql注入，…必须立刻查看代码；
3. MAJOR：可能会影响开发者效率的质量缺陷：未覆盖的代码，重复块，未使用的参数….
4. MINOR：可能会影响开发者效率的质量缺陷：每行不能太长，“switch”语句应该至少有三个条件，….
5. INFO：既不是缺陷也不是质量问题，只是一个发现。

SonarQube 问题工作流可以帮助你管理这些问题。你有七种方法处理这些问题（不是在代码中修复）：注释，分派，确认，改变严重性，已解决，不会被修复，假阳性。这些可以分为以下三类。

Technical Review

1. Confirm:通过确认一个问题，将其从“open”状态转换为“Confirm”。
2. False Positive:在全文中查看问题，发现不是一个真正的问题，标记为“False Positive”；
3. Won’t Fix:在全文中查看问题，发现不是一个有效的问题，即可以被接受的技术债；
4. Change Severity:是一个问题，但不是一个坏问题，或者是一个更严重的问题，根据自己的经验来调整严重等级；
5. Resolve：如果你认为你已经修复了一个开放的问题，你可以解决它。如果修改正确，下次执行时将会关闭状态，若修改不正确，下次执行分析后，状态仍然保持开放。

如果标记出很多问题是属于False Positive和Won’t Fix，说明编码规则不适合现有的背景，你可以在 quality profile 中修改或使用问题包含来聚焦规则使用于特定的部分。类似的，若
严重性变更过多，也得考虑更新文件中规则了。

Dispositioning

通过了Technical Review之后，该决定由谁来解决问题了。默认是由最后一个提交者负责，你也可以重新分配给自己或者其他人。被分配者会接收到邮件通知。

General

在问题生命期中任何时候，你都可以注释问题。在运行日志中显示出细节注释。你也可以编辑或删除你做的注释。

Bulk Change

所有的这些变更都可以一次性做成多个问题，通过使用问题搜索结果面板的Bulk Change。

其他：问题来源于规则或者收集在文件中的规则。只有指定的用户才能编辑文件，但所有用户都可以查看它们。

---

Rules

略

---

Metric Definition

• Complexity
• Documentation
• Duplications
• Issues
• Maintainability
• Quality Gates
• Reliability
• Security
• Tests

Complexity

• Complexity:基于代码路径数量计算复杂度。功能控制流分裂，复杂度依次增加。每个功能最小复杂度为1.由于关键词和功能原因，不同语言复杂度计算有些不同。
• Complexity/class:类的平均复杂度
• Complexity/file：文件的平均复杂度
• Complexity/method：函数的平均复杂度

Documentation

• Commment lines:包含注释或注释代码的行数。不包括仅有注释符号的行数。可参见官网本节有关注释代码的例子。http://docs.sonarqube.org/display/SONAR/Metric+Definitions
• Comments(%):注释行数密度=注释行数/(代码行数+注释行数)*100（50%表示代码行数与注释行数相同，100%表示只有注释行）
• Public documented API(%)：公有记录API密度=（公有的API-公有未记录的API）/公有API*100
• Public undocumented API：不带注释头的公有API
• Commented-out LOC:代码注释行数

Duplications

• Duplicated blocks:重复代码块行数
• Duplicated files:重复文件数
• Duplicated lines:重复行数
• Duplicated lines(%):重复密度=重复行数/总行数*100

Issues

• New issues
• New xxxxx issues
• Issues
• xxxxx issues
• False positive issues
• Open issues
• Confirmed issues
• Reopened issues

Severity

• Blocker:致命的
• Critical:关键的
• Major:主要的
• Minor:微小的
• Info：未知的

Maintainability

• Code smells
• New code smells
• Maintainability Rating:A=0-0.05, B=0.06-0.1, C=0.11-0.20, D=0.21-0.5, E=0.51-1
• Technical Debt:技术债，修复所有维护问题的成本。
• Technical Debt on new code：新代码上的技术债
• Technical Debt Ratio：技术债比例=修复成本/开发成本
• Technical Debt Ratio on new code：开发者变更代码的花费与相关问题的花费比

Quality Gate

• Quality Gate Status:有ERROR,WARN,OK三种状态
• Quality Gate Details:质量门各种条件的细节

Reliability

• Bugs
• New Bugs

• Reliability Rating:

  • A = 0 Bug
  • B = at least 1 Minor Bug
  • C = at least 1 Major Bug
  • D = at least 1 Critical Bug
  • E = at least 1 Blocker Bug

• Reliability remediation effort:修复所有缺陷问题成本

• Reliability remediation effort on new code：在新增代码上修复所有缺陷问题成本

Security

• Vulnerabilities
• New Vulnerabilities
• Security Rating:
  
  • A = 0 Vulnerability
  • B = at least 1 Minor Vulnerability
  • C = at least 1 Major Vulnerability
  • D = at least 1 Critical Vulnerability
  • E = at least 1 Blocker Vulnerability
• Security remediation effort
• Security remediation effort on new code

详细度量：Classes, Directories,files,lines(显示的行数),lines of code（包括至少一个字符，不包括空格）,lines of code per language,methods,projects,public API（公有类数量+公有方法数量+公有属性数量）,Statements.

Tests

• Condition coverage on new code：新增或更新代码的条件覆盖度
• coverage on new code：新增或更新代码的覆盖度
• Line coverage on new code：新增或更新代码的行覆盖度
• Lines to cover on new code：新增或更新代码覆盖的行数
• Uncovered conditions on new code：新增或更新代码未覆盖的条件数
• Uncovered lines on new code：新增或更新代码未覆盖的行数
• Coverage：行覆盖和条件覆盖的混合。单元测试覆盖多少源代码。Coverage = (CT + CF + LC)/(2*B + EL)，其中
  
  • CT = conditions that have been evaluated to ‘true’ at least once
  • CF = conditions that have been evaluated to ‘false’ at least once
  • LC = covered lines = lines_to_cover uncovered_lines
  • B = total number of conditions
  • EL = total number of executable lines (lines_to_cover)
• Condition coverage hits：条件覆盖的列表
• Line coverage hits：行覆盖的列表
• Conditions by line：行条件数
• Uncovered conditions：单元测试未覆盖的条件数
• Covered conditions by line：行覆盖的条件数
• Uncovered lines：单元测试没有覆盖的代码行数
• Lines to cover：单元测试可能覆盖的代码行数
• Skipped unit tests：跳过的单元测试数量
• Unit test failures：异常的单元测试数量
• Unit test errors：失败的单元测试数量
• Unit tests：单元测试数量
• Line coverage：单元测试覆盖行数密度
  
  • Line coverage = LC / EL
  • LC = covered lines (lines_to_cover - uncovered_lines)
  • EL = total number of executable lines (lines_to_cover)
• Condition coverage：Condition Coverage=（CT+CF）/(2*B)
  
  • CT = 至少一次使用 ‘true’的条件数
  • CF = 至少一次使用 ‘false’ 的条件数
  • B = 条件总数
• Unit test success density (%)：测试成功密度=（单元测试总数-（单元测试错误数+单元测试失败数））/单元测试数*100
• Unit tests duration:执行所有单元测试所需的时间

若对此节不清楚，可以参考官方文档。由于本人水平有限，翻译仅供参考。