直接从代码中管理您的技术债务路线图🚀

概要：

• 技术债务会导致缺陷的产生：软件工程研究所的一项研究表明，缺陷数量与设计缺陷（技术债务）数量之间的相关性为 0.92。
• 像 SonarQube 这样的静态分析工具被广泛用于（超过 10 万用户）查找质量缺陷，但它们无法取代人类智能。
• 缺陷跟踪系统既耗时，又无法帮助开发人员编写代码。
• 我们的工具Tyrion可以解决这些问题，并允许开发人员直接在 IDE 中查看质量问题。

质量值得投资

Martin Fowler 在他关于软件质量的著名文章中解释了
为什么投资软件质量比不投资软件质量更划算。

精益实践者早已熟知这一道理：
“如果你专注于质量，就能按时交付高质量的产品；
如果你专注于交付，就会延迟交付低质量的产品。 ”

为什么呢？如果你专注于一次性把事情做好，就能减少返工，从长远来看就能节省时间。而那些做不到这一点的团队，最终会把大部分时间都花在修复漏洞上。

静态分析工具是必需的，但不足以监控质量。

一旦你确定要长期保证质量，就有很多事情要做：确定最佳实践、技术培训、解决问题、质量工具、建立各种监控机制、选择质量关键绩效指标……

如果你真心想要保持代码库的高质量，就需要主动追踪、监控并解决代码质量缺陷。即使你已经设置了所有最佳的代码检查规则，并且拥有一支训练有素的团队，从长远来看，缺陷仍然不可避免。事实上，有很多缺陷是代码检查工具无法检测到的：例如代码和架构不一致、模式使用不当、命名与业务逻辑不符等等。

一种广泛应用的策略是使用静态分析工具（例如SonarQube或CodeClimate）来监控质量。
这些工具具有以下优势：

• ✔️无需开发人员额外工作，您即可获得质量评分（工具设置完成后，设置过程可能很快）。
• ✔️结果客观
• ✔️他们会列出你需要修改的代码片段以及你没有遵循的良好实践。

你可以生成类似这样的图表，它可以显示你的技术债务趋势，并告诉你情况是在好转还是恶化。

在与技术主管和首席技术官交谈时，他们中的许多人告诉我，SonarQube 有效地帮助他们的团队保持了高质量的代码。

静态代码分析工具 (SCAT) 提供关于代码质量和技术债务的客观指标和深入见解。然而，这些工具需要团队投入大量精力进行集成。如果团队没有采用和培训，这些工具的价值就微乎其微。相反，如果由训练有素、对指标和警告有务实理解的开发人员使用，这些工​​具可以提供许多线索，帮助确定下一步需要进行的重构以降低项目熵，确定仍需解决的安全漏洞以及需要审查的潜在缺陷。SCAT 的警告和建议应作为开发人员围绕质量标准展开讨论的起点。SCAT 不应被视为评判项目或团队质量优劣的裁判。—— Guillaume Michel，Theodo，副总裁工程师

一些研究也证明了其有效性，例如
Oswal, Nikhil.“技术债务：识别、衡量和监控。” (2019)

然而，这些工具也存在局限性：

• ❌ 它们会产生大量的误报（将一段好的代码标记为坏的）和漏报（漏掉一些坏的代码），需要时间来整理所有内容。
• ❌ 他们无法检查项目的所有方面。例如，一些缺陷，如目录组织错误或不一致，可能永远无法被发现。

学术研究虽然证实了静态分析工具的积极作用，但也强调它们尚不成熟，不能完全依赖它们。例如，为了评估缺陷是否会导致 bug，Valentina Lenarduzz 在她 2019 年的研究报告《SonarQube 规则是否会导致 bug？》中警告我们：“ SonarQube 违规的严重程度与故障倾向性无关，因此，开发人员在决定是否重构违规代码时，应仔细考虑违规的严重程度。 ”

这正是比尔·克拉克在他的文章《技术债务分类》中解释得非常清楚的一点：
人类可以提供关于一段存在技术债务的代码的更多有价值的信息，例如其传染性：“这种糟糕的代码实践是否有可能通过复制/粘贴传播到其他地方？”

有效的质量监控需要人工分析

正如我们刚才看到的，人工分析可以为静态分析工具提供补充信息：

• ✔️人可以分析项目的各个方面：架构、命名、易懂性、库和框架的成熟度
• ✔️由于他们了解代码库的上下文，因此可以提供更多关于他们检测到的问题的信息。
• ✔️他们可以对问题进行优先级排序。

团队中的开发人员接受的编写高质量代码方面的培训越多，他们就越能高效地发现缺陷。这也是为什么如果你想要高质量的代码，就应该在培训方面投入大量资源的原因之一。

你们还需要就最佳的编写方式达成一致：哪些代码写法可以接受，哪些不可以。
例如，以下两段代码在 Symfony 中实现的是完全相同的功能。

/**
* @ORM\Column(unique=true)
*/
private $email;


/**
* @ORM\Column(type="string", length=255, unique=true)
*/
private $email;

两种方法各有优势：前者编写/阅读更简洁，后者更清晰明了。我更喜欢清晰明了的版本，因为我认为在这种情况下，代码清晰易懂与编写/阅读字数增加之间的权衡是值得的。有些人可能会认为，由于类型和长度是默认值，所以没有必要再添加它们。

谁对谁错并不重要，重要的是团队要达成共识，采用标准的方法。因为一旦达成共识，每个人都可以自主地按照这个标准编写代码并检查质量，从而逐步使整个代码库保持一致性。

人工分析的主要缺点是需要花费大量精力来获取和更新有关整体质量的信息。

现有工具耗时费力，而且对开发人员编写代码没有帮助。

在 Theodo，我们体验了几个用于跟踪自我承认的技术债务（软件质量研究人员称之为SATD ）的系统。

1. 对于小型或短期项目，我们会在 Trello/Jira/Monday/Google 文档中使用专门的列来跟踪修复质量问题所需的任务。只要团队能够快速修复所有问题，这种方法就行得通，这样列就不会变得太长太杂乱。

2. 随着项目的发展，我们需要在单独的看板上制定一个真正的技术路线图。

我们还可以使用像Bugzilla或Bugherd这样的专业缺陷跟踪工具。
它运行良好，但有两个缺点：

• ❌ 当某个物品被修复或不再有效时，更新它会很耗时。
• ❌ 开发人员在编写代码时无法在 IDE 中看到缺陷，因此可能会复制/粘贴，从而造成 Bill Clark 所解释的债务的传染性。

Tyrion 简介：一款通过人工分析帮助团队跟踪软件质量的工具

我让提利昂去消除这些主要缺点，以便他能够：

• ✔️在集成开发环境 (IDE) 中直接编写代码的同时记录债务。
• ✔️问题解决后，轻松更新债务跟踪系统。
• ✔️快速了解债务概况和趋势

在代码中添加注释来映射债务

Tyrion 的核心理念并非将所有技术缺陷都记录在工具中，而是直接以注释的形式添加到代码库中。Tyrion 会解析这些注释，生成缺陷图表或 CSV 文件，以便您分析缺陷。

注释的语法很简单：你只需要在经典注释中添加一个类型，以便 Tyrion 可以对它们进行分组：

// TODO DEBT_TYPE "Author: comment"

我喜欢以下这个来自当前项目的例子。Albéric 和 Emyly 正在努力提升网页应用的易用性。业务上没有什么紧急情况，技术上也不需要立即进行任何更改。但他们仍然知道这段代码可以做得更好，所以他们把它标记为待办事项，打算稍后进行改进。

// TODO accessibility "Alberic: Add keyboard behaviours and focusability"
export const Select: React.FC<Props> = ({

即使不使用 Tyrion，在代码中添加代码债务注释本身也很有价值。它能训练开发者在编写代码的同时评估代码质量。此外，它还能在一定程度上防止代码债务的蔓延，因为如果你用注释正确地标记了
代码中的债务，开发者在复制粘贴被标记为债务的代码片段之前就会三思。

如果你的代码库很大，记录所有技术债务可能需要一些时间。你可以分阶段进行，用几周时间完成。团队成员在开发应用程序的各个部分时，会阅读不同的文件，找出需要标记为技术债务的内容。通过这种方式，你可以逐步构建项目的债务地图。
当然，最好是发现问题就立即修复，但由于各种原因，你并非总有时间这样做。

如果你的项目规模适中，你也可以安排一个下午进行一次大型的债务梳理会议。

使用 CLI 生成第一个图表

一旦你对项目中的债务至少进行了一部分注释，你就可以开始使用 Tyrion CLI 了。

首先你需要使用以下命令下载它：npm i -g tyrionl或yarn global add tyrionl

然后只需tyrion在项目根目录下运行即可。
它会扫描文件，查找注释中的TODO“, FIXME”或@debt字符串，然后将其判定为债务注释。

第一种模式有助于了解您项目的当前债务状况。它可以帮助您回答诸如“我们现在有多少债务？”或“我们最大的债务类型是什么？”之类的问题。

如果我在 Web 应用程序的前端部分运行 Tyrion，我会得到以下图表，其中我们可以 从上述债务注释中找到债务acessibility类型，以及我们在项目中使用的其他类型。

您可以自定义每种债务类型在全球债务评分中的权重。

并非所有类型的债务都会产生相同的影响。安全问题可能比过于复杂的功能更为严重。因此，您可能需要对每种类型的债务赋予不同的权重。这可以通过.tyrion-config.json在项目根目录创建一个文件来实现。然后，您可以为每种类型的债务分配不同的值。

以下是默认配置：

{
  "pricer": {
    "bug": 100,
    "architecture": 100,
    "bugRisk": 5,
    "security": 100,
    "securityRisk": 10,
    "quality": 5,
    "test": 5,
    "doc": 3,
    "ci": 30,
    "deploy": 10,
    "devEnv": 10,
    "outdated": 5
  },
  "standard": 100,
  "ignorePath": [
    "node_modules",
    "README.md"
  ]
}

您可以在README 文件中找到有关如何使用 Tyrion 的更多信息。

债务趋势可能是最重要的信息

在代码中注释一段时间的债务之后，您将可以使用第二种模式，该模式会分析您的 Git
历史记录并生成债务演变图。获取该图的命令是 `git checkout -d` tyrion -e 200。您可以将 `-d` 替换200为您想要回溯扫描的天数。

这类报告将帮助您和您的团队回答“我们是在增加债务还是在提升质量？”这个问题。
了解这一点至关重要，因为如果您的债务呈上升趋势，您就应该加大对质量的投入。
记住，忽视质量并不会让您发展得更快😉。

与产品/业务团队分享

如果你正在阅读这篇文章，你很可能是一名开发人员，你可能希望花更多时间在质量上。但你可能无法做到这一点，因为项目业务部门的某些人更希望你专注于短期交付。

所以你需要和这个人谈判。这个工具也是为了帮助你进行谈判而开发的，它会提供图表和数据
来支持你的论点。

如果您需要生成一个 csv 文件以便业务人员更详细地查看数据，您可以使用该选项生成它--csv。

结论

多年来保持项目代码的高质量是一项非常困难的任务。在项目中使用 Tyrion 的一个积极作用是，开发人员可以在编码过程中培养质量意识。如果团队中的所有开发人员在编写/阅读每个功能时都问自己“我正在编写/阅读的这段代码是否是我们能做到的最佳水平？”，那么你们就能很好地确保长期保持高质量的代码。

我很乐意与您探讨Tyrion和质量管理方面的问题。请随时联系我：

• 📧 通过电子邮件
• 🐦 在推特上
• 🐙 通过在Tyrion 代码库中提交 issue 或 pull request 来解决这个问题
• 💬 请在下方留言