喝咖啡休息#20。什么是遗留代码以及如何使用它。使编写技术文档变得更容易的工具

什么是遗留代码以及如何使用它

资料来源：Dou 迟早，程序员可能会遇到遗留代码。为了减轻这种熟悉的后果，我从自己的经验中选择了一些实用的技巧和示例 - 特别是使用遗留 Java 系统的经验。

旧版功能

遗留代码是别人的代码，通常非常糟糕，以至于人们通常不清楚如何使用它。而如果你必须使用遗留系统，除了旧代码之外，你还会遇到：

• 技术过时；
• 异构架构；
• 缺乏甚至完全没有文档。

事实上，遗留代码并没有那么可怕，原因如下：如果系统已经存在了这十年并且仍在工作，那么它还有一些用处。也许它能赚很多钱（与你上一次创业不同）。此外，如果这段代码能够在生产环境中存活这么长时间，那么它是相对可靠的。因此，对其进行更改必须谨慎。首先，你需要明白两件事：

1. 我们不能不尊重一个赚了数百万美元或每天有数千人访问的系统。不管写得多么糟糕，这段令人作呕的代码仍然可以在生产环境中存活下来并全天候（24/7）运行。

2. 由于这个系统带来了真正的金钱，因此使用它需要承担很大的责任。这不是一家初创公司，而是用户明天将使用的东西。这也意味着错误的成本非常高，而且这里的重点不在于客户的主张，而在于事情的真实状况。

逆向工程

要成功使用遗留代码，您必须使用逆向工程技术。首先，您需要仔细阅读代码以准确理解其工作原理。这是强制性的，因为我们很可能没有文档。如果我们不理解作者的思路，我们就会做出改变，后果难以预料。为了保护自己免受这种情况的影响，您还需要深入研究相邻的代码。同时，不仅要向广度迈进，还要向深度迈进。调用错误的方法在哪里？调用它的代码从哪里来？在遗留项目中，“调用层次结构”和“类型层次结构”比其他任何东西都更常用。您将不得不花费大量时间使用调试器：首先，查找错误，其次，了解一切是如何工作的。至于文献记载，借助工业考古学也不失为一个好主意。在某处挖掘旧文档并与那些记得您继承的代码是如何编写的人交谈是非常有用的。使用这些技术，迟早您将开始或多或少地理解代码。但为了防止你的努力白费，你必须立即记录你的研究结果。为此，我建议绘制框图或序列图。当然，你会很懒，但你肯定需要这样做，否则在没有文档的六个月内，你将像第一次一样挖掘这段代码。

不要重写代码

开发过程中最重要的是按时打败自己，而不是试图从头开始重写整个代码。估计这需要多少人年。客户不太可能愿意花这么多钱来重做已经可以使用的东西。这不仅适用于整个系统，也适用于系统的任何部分。当然，他们可能会给你一周的时间来解决所有问题，然后再给你一周的时间来修复某些问题。但他们不太可能给你两个月的时间来重新编写系统的一部分。相反，以与其余代码相同的风格实现新功能。换句话说，如果代码很旧，您不应该尝试使用新的漂亮技术：这样的代码将很难阅读。例如，您可能会遇到像我们这样的情况：系统的一部分是用Spring MVC编写的，一部分是用裸servlet编写的。如果在 servlet 中编写的部分中需要添加其他内容，那么我们以相同的方式添加它 - 在 servlet 中。

尊重商业利益

必须记住，任何任务首先都是由业务价值决定的。如果你不向客户证明从业务角度需要进行某些改变，这些改变就不会发生。而为了说服客户，你必须试着站在他的立场上，了解他的兴趣。特别是，如果您只是因为代码难以阅读而想要重构，那么您将不被允许这样做，并且您必须忍受它。如果实在无法忍受，可以悄悄地、一点一点地重新整理代码，将工作分散到各个业务票上。或者让客户相信，这将减少发现错误所需的时间，从而最终降低成本。

测试

显然，任何项目中都需要进行测试。但是，在使用遗留系统时，还必须特别注意测试，因为所做更改的影响并不总是可预测的。您至少需要与开发人员一样多的测试人员，否则您应该非常擅长自动化。在我们的项目中，测试包括以下阶段：

1. 验证，在单独的分支中检查功能的实现功能时。
2. 稳定性，当检查发布分支时，所有功能都合并在一起。
3. 认证，即在硬件特性和配置方面尽可能接近生产的认证环境中，在略有不同的测试用例上再次运行相同的事物。

只有经历了这三个阶段，我们才能发布。有人可能认为认证是一个额外的阶段，因为一切都已经在稳定阶段得到澄清，但我们的经验表明事实并非如此：有时在回归测试期间，在另一台机器上运行第二轮，不知何故它会出来的。

正式化 DevOps 和发布

例如，释放过程可以如下。当开发完成并且完成两个或三个测试阶段时，我们会在预计发布时间前 36 小时向 DevOps 团队写一封电子邮件。之后，我们致电 DevOps 团队并讨论环境中的所有更改（我们通知他们数据库和配置中的所有更改）。对于每次更改，我们都有一个文档（Jira 中的票证）。然后发布的时候，所有参与这个的人都聚在一起，每个人都说自己现在在做什么：“我们上传了数据库”，“我们重新启动了某某服务器”，“我们去生产环境跑回归测试了。” ” 如果出现问题，则会启动发布回滚程序，这与原始发布文档中的描述完全一致 - 如果没有这样的文档，我们肯定会忘记某些内容或感到困惑。

控制代码质量

最后，由于某种原因，代码审查这种做法并未在所有项目中使用。如果每一段代码都由多个人审查，那就太好了。即使在一个非常强大的团队中，在代码审查过程中也总会发现一些错误，如果几个人一起看，发现的错误数量就会增加。此外，有时第三个或第四个审稿人会发现最糟糕的事情。

使编写技术文档变得更容易的工具

来源：Dzone 大多数程序员不喜欢编写技术文档。心理学专家 Gerald Weinberg 甚至将文档称为“编程的蓖麻油”：开发人员喜欢阅读它，但他们只是讨厌自己编写它。 缺乏指导或空白的路线图会导致缺乏有关软件不同部分如何工作的信息。这最终会恶化代码最终用户的体验，因为在没有文档的情况下，他们无法依赖产品的准确性和实用性。为了让程序员更容易养成编写文档的习惯，我建议关注现在几乎每个人都可以使用的四个优秀工具。

GitHub 页面

如今，可能没有一个开发人员没有在 GitHub 上工作的经验。对于需要存储文档的程序员来说，这也是一个好地方。许多人在代码库中使用标准自述文件来为用户提供简单的操作指南，但这并不是在 GitHub 上创建文档的唯一方法。借助GitHub Pages，您获得的不仅仅是托管项目页面，还包括文档和教程。您能够直接与所有 GitHub 存储库进行交互，从而使开发人员能够像更新代码一样更新文档。此外，您可以在这里使用Jekyll - 它可以帮助您将标记转换为纯文本或成熟的网页。

阅读文档

顾名思义，Read the Docs为开发人员提供了一个存储和阅读文档的平台。该服务的工作方式与 GitHub Pages 非常相似：程序员可以从他们最喜欢的版本控制系统（包括 Git、Bazaar、Mercurial 等）对文档进行更改。还支持自动版本控制和页面创建。Read Docs 最好的部分是它的灵活性。它支持 Webhook，因此您可以自动化大部分文档创建过程。对于大多数程序员不想做的任务来说，这可以节省大量时间。此外，该平台上托管的所有内容都可以多种格式向公众开放，包括 PDF、单页 HTML，甚至电子书格式。该服务承担了保持文档最新的日常工作的重要部分。

泰特拉

Tettra不仅仅是一个存储软件文档的平台，而且是一个完整的知识库。当一个项目涉及一大群开发不同软件的程序员时，它的效果尤其好。Tettra 可用于记录常见问题的答案。

蜂房

Apiary对开发人员如此有用的原因是它在帮助 API 文档方面做得非常出色。该平台允许用户用Markdown编写文档，包括模拟 API 调用。Apiary 还允许您测试 API 元素并制作原型。换句话说，它是一个文档工具和测试平台。