中断,中断向量,中断向量表_我们的团队中断了即时旧版发布，您也可以

中断,中断向量,中断向量表

by Jonathan Solórzano-Hamilton

乔纳森·索洛萨诺·汉密尔顿(JonathanSolórzano-Hamilton)

我们的团队如何与“即时遗留”代码版本分手-以及如何 (How our team broke up with “instant-legacy” code releases — and how you can too)

The concept of legacy conveys permanence, value, and the greatness we bequeath to our children and our successors in the community.

遗产的概念传达了我们留给我们的孩子和社区继承者的永久性，价值和伟大。

People make ludicrously generous donations to charitable causes to establish their legacy. They create eponymous endowments or buildings and strive to protect the name their children will inherit.

人们为慈善事业慷慨捐赠，以建立自己的遗产。 他们创造了同名的end赋或建筑物，并努力保护孩子将继承的名字。

It’s therefore striking that software developers have gotten their “legacy” so catastrophically wrong.

因此，令人震惊的是，软件开发人员的灾难性错误使他们的“传统”成为现实。

Google “legacy,” and you’ll see the first definition matches what I’ve laid out for you here. It’s a definition that’s persisted since the 14th or 15th century.

Google的“旧版”，您会在这里看到第一个定义与我为您列出的定义相符。 这是自14或15世纪以来一直存在的定义。

The second definition provides a shocking contrast:

第二个定义提供了令人震惊的对比：

legacy. adjective (computing) “denoting software or hardware that has been superseded but is difficult to replace because of its wide use.

遗产。 形容词(计算)“表示已被取代但由于其用途广泛而难以替换的软件或硬件。

Dictionaries around the internet agree with this definition. It applies only to the field of computing. We developers have managed to invert the definition of our own legacy in the historical eye-blink that is computer science. That’s almost impressive!

互联网上的字典同意这个定义。 它仅适用于计算领域。 我们的开发人员已经设法在计算机科学的历史眨眼间反转了我们自己的遗产的定义。 简直令人印象深刻！

If you’re an experienced developer, you’ve certainly been tasked with supporting at least one legacy system in your career. For the uninitiated, well — buy a lot of caffeinated beverages.

如果您是一位经验丰富的开发人员，那么您肯定会在您的职业生涯中受过支持至少一个旧系统的任务。 对于初学者来说，很好-购买大量含咖啡因的饮料。

I’m about to relate to you the brief story of our toxic relationship with our legacy codebase. I’ll then describe how we broke up with it, and what we’ve changed to avoid falling back into bad relationships with high-maintenance code.

我将向您介绍我们与遗留代码库之间的不良关系。 然后，我将描述我们如何分解它，以及我们为避免与高维护代码陷入不良关系而进行的更改。

分手 (The Breakup)

It took eight months of seven-day weeks and twelve-hour days to complete our last legacy system overhaul.

完成我们的最后一次旧系统检修需要花八个月的七个星期的时间和十二个小时的时间。

Our predecessors had pushed code into production for years without writing a single line of documentation. In fact, some of it wasn’t even in source control, as we later learned. But that’s another story.

我们的前任将代码推入生产已经多年了，而没有编写任何文档。 实际上，正如我们后来了解到的那样，其中一些甚至不在源代码控制中。 但这是另一个故事。

I’m sure you’ve seen gems like this before:

我确定您之前看过这样的宝石：

... hundreds of line of incomprehensible code

// TODO: Fix this bug!!!

... hundreds more lines in the same method, no idea where or what the bug is

That is the approximate ratio and quality of the only documentation we had on the project.

那是我们在该项目上拥有的唯一文档的近似比率和质量。

I wasn’t exposed to direct sunlight again until April, and I’d had enough. It was time for a break-up.

直到四月，我才没有再次暴露在直射的阳光下，我受够了。 是时候分手了。

文件的重要性 (The importance of documentation)

In his book “The Art of Unit Testing,” Roy Osherove defines legacy code as any code that doesn’t have tests. He was an optimist. I more loosely regard as legacy any code which contains more technical debt than the time it took to write.

Roy Osherove在他的《单元测试的艺术》一书中将遗留代码定义为任何没有测试的代码。 他是一个乐观主义者。 我更宽松地将任何包含比编写时间 更多的技术债务的代码视为遗留代码。

As our organization had, many development teams fall into the trap of instant-legacy code: code that already fits the “legacy code” label at the time of release.

就像我们组织一样，许多开发团队陷入了即时遗留代码的陷阱：发布时已经适合“遗留代码”标签的代码。

In my experience, documentation is the most important aspect of avoiding such legacy code.

以我的经验，文档是避免此类遗留代码的最重要方面。

I have yet to meet a developer who loves the idea of documentation. On the other hand, I also have never met a developer who loves crawling inside the skull of a stranger to reverse-engineer a legacy implementation without any documentation.

我还没有遇到喜欢文档想法的开发人员。 另一方面，我也从未遇到过喜欢在陌生人的头上爬行以对没有任何文档的旧版实现进行反向工程的开发人员。

As they say, breaking up is hard to do. But in this case, I promise it will be worth it.

正如他们所说，分手很难。 但是在这种情况下，我保证这是值得的。

So let’s get started on converting your legacy into something you’ll be proud to bequeath to your successors. Let’s get documenting!

因此，让我们开始将您的遗产转换为您可以继承给继承人的东西。 让我们开始记录吧！

我们的方法：四层文档 (Our approach: four layers of documentation)

We created, and began rigorously following, a four-layer architecture for documentation. We maintain three layers of persistent documentation for the project through its life-cycle. We also communicate through one layer of ephemeral documentation during our release management process.

我们创建并严格遵循四层文档架构。 我们在项目的整个生命周期中维护三层持久性文档。 在发布管理过程中，我们还通过一层临时文档进行通信。

The three persistent layers of documentation correlate to three different velocities in our development process. We include documentation review as part of code review to avoid falling back into bad habits.

文档的三个持久层与我们开发过程中的三个不同速度相关。 我们将文档审查作为代码审查的一部分，以避免陷入不良习惯。

//前线：内联注释使维护者保持理智 (// The front lines: in-line comments keep maintainers sane)

The most granular tier of explicit documentation is in the code. We perform complete documentation of all classes and methods, their inputs, expected outputs, and exception pathways. We also document “unusual” code in-line.

显式文档的最精细层位于代码中。 我们对所有类和方法，它们的输入，预期的输出以及异常路径进行完整的记录。 我们还在线记录“异常”代码。

As a predominantly C# shop we use /// documentation ubiquitously. This decorates class, interface, and method declarations. The /// helper auto-generates XML stubs to document the nuts and bolts of the API.

作为主要的C＃商店，我们无处不在使用///文档。 这将装饰类，接口和方法声明。 ///帮助程序会自动生成XML存根，以记录API的基本内容。

These pop up when your code is being referenced by an external project or DLL (dynamic-link library), provided that you’ve distributed the debugging files. Our IDE (integrated development environment) renders this as tool-tip help wherever a reference appears. This greatly aids developers, who are diving into our code for the first time, when trying to fix a bug or extend it for a new use case.

如果您已分发调试文件，则当外部项目或DLL(动态链接库)引用您的代码时，将弹出这些对话框。 无论何时出现参考，我们的IDE(集成开发环境)都将其呈现为工具提示帮助。 这对于第一次修复我们的代码的开发人员有很大的帮助，他们可以尝试修复错误或将其扩展为新的用例。

It’s worth researching your language and IDE of choice to learn how to extend it with contextual help for your libraries. If you’re not used to documenting your APIs, I suggest reading these articles to get started.

值得研究您选择的语言和IDE，以了解如何通过上下文帮助扩展库。 如果您不习惯于记录API，建议您阅读这些 文章以开始使用。

We also include regular // comments beyond API documentation. We add these wherever the code is counter-intuitive, or if we’ve found a particularly elegant solution to a problem. We also use these to create “to-do’s” for later refactor when putting in a quick-and-dirty fix.

除了API文档外，我们还提供常规//注释。 我们将这些代码添加到代码违反直觉的任何地方，或者找到解决问题的特别优雅的方法。 我们还使用它们来创建“待办事项”，以便日后进行快速修复时进行重构。

These are invaluable to whoever has to come along and revert the change or fix the code.

对于必须随手来恢复更改或修复代码的人来说，这些都是无价的。

Because it’s in-line with the source code, this documentation changes at the highest velocity — right along with the code it supports.

因为它与源代码一致，所以本文档及其支持的代码以最快的速度更改。

自述文件：使实施变得轻而易举 (README: making implementation a breeze)

We use README files as an implementer’s guide. This documentation is for whoever will be consuming our libraries. It serves a secondary purpose as tactical-level documentation of the particulars of the implementation.

我们使用README文件作为实施指南。 本文档适用于将使用我们的库的任何人。 它作为实现细节的战术级文档而具有辅助作用。

We use GitHub for source control, so we place readme.md (Markdown) files in each folder in our GitHub repository. GitHub very nicely renders Markdown files and automatically shows the rendered readme.md files in each folder. This results in a much more usable help file than a simple .txt document.

我们使用GitHub进行源代码控制，因此将readme.md( Markdown )文件放在GitHub存储库中的每个文件夹中。 GitHub很好地呈现了Markdown文件，并自动在每个文件夹中显示了呈现的readme.md文件。 与简单的.txt文档相比，这将产生更多有用的帮助文件。

Storing this documentation in the code-base helps developers maintain the documentation. Anyone making a code change can easily open the .MD file in their source code editor or an online markdown editor, and immediately update the documentation.

将此文档存储在代码库中可帮助开发人员维护文档。 进行代码更改的任何人都可以在其源代码编辑器或在线Markdown编辑器中轻松打开.MD文件，并立即更新文档。

Thus the source-controlled Markdown files live next to, but not within, the code they support. It’s also somewhat more “zoomed out” than inline comments. These two factors result in a lower velocity of updates on this documentation. Because you can still include it in the same commits it changes with higher velocity than offline documentation.

因此，源代码控制的Markdown文件位于它们支持的代码的旁边，而不是位于其中。 它比嵌入式注释还“缩小”了。 这两个因素导致本文档的更新速度降低。 因为您仍可以将其包含在同一提交中，所以它的更改速度要比脱机文档高。

The final advantage of this format is that anyone who downloads the source code has immediate access to the implementation guides. Coupled with the inline documentation, this provides both maintainers and consumers with sufficient documentation. They can develop a basic understanding of the project without jumping into another system, such as a wiki.

这种格式的最终​​优势是，下载源代码的任何人都可以立即访问实施指南。 结合内联文档，这可以为维护者和使用者提供足够的文档。 他们可以对项目有基本的了解，而无需跳入另一个系统，例如Wiki。

Wiki：业务与发展相遇的地方 (Wiki: where business meets development)

We use the wiki-level documentation to marry the implementation to the business requirements. This documentation consists primarily of requirements, enterprise architecture diagrams and considerations, and tactical diagrams such as unified modeling language (UML) flow charts and class diagrams.

我们使用Wiki级文档将实现与业务需求结合起来。 本文档主要由需求，企业体系结构图和注意事项以及战术图(例如统一建模语言(UML)流程图和类图)组成。

We also use pages (on the same wiki) as meeting minutes, and to record decisions. We use a wiki which has versioning so that we can see a complete history of how requirements and designs have changed over time.

我们还使用页面(在同一Wiki上)作为会议记录，并记录决策。 我们使用具有版本控制的Wiki，以便我们可以查看有关需求和设计如何随时间变化的完整历史记录。

We thereby ensure a complete history of the requirements process and how it relates to the changing architecture. Incidentally, GitHub also provides a wiki feature, but we use a third-party wiki which integrates with our project management software.

因此，我们确保了需求过程的完整历史记录以及它与不断变化的体系结构之间的关系。 顺便说一句，GitHub还提供了Wiki功能，但是我们使用了与我们的项目管理软件集成的第三方Wiki。

发布管理：提交和拉取请求注释 (Release management: commit and pull request comments)

Our release management process includes code review. Our code review includes documentation review.

我们的发布管理过程包括代码审查 。 我们的代码审查包括文档审查 。

As GitHub is our source control platform, we bake code review into our pull requests. The platform supports commenting upon check-in, inline comment threads on portions of commits, and a conversation thread on the pull request.

由于GitHub是我们的源代码控制平台，因此我们将代码审查纳入我们的请求请求中。 该平台支持签入时的注释，提交部分的内联注释线程以及拉取请求中的会话线程。

The key to using these communication channels successfully is to ensure that all discussions result in a tangible output. Either clarify the code itself, or extend the permanent documentation in response to questions.

成功使用这些沟通渠道的关键是确保所有讨论都能产生切实的成果。 要么澄清代码本身，要么扩展永久文档以回答问题。

If the reviewer doesn’t understand the code as it is written, future developers won’t either. Rewrite the code to be more self-explanatory, or extend the in-line or readme documentation.

如果审阅者不理解所编写的代码，那么将来的开发人员也不会。 重写代码使其更加不言自明，或者扩展内联或自述文档。

It’s not sufficient to end the conversation by replying to the thread: we treat this documentation as ephemeral, and on a long-lived code-base it’s a pain to review the full commit history.

仅仅通过回复线程来结束对话是不够的：我们将此文档视为短暂的，并且在长期存在的代码库中，查看完整的提交历史很痛苦。

奖金回合：自我证明代码 (Bonus round: self-documenting code)

Finally, one quick plug for so-called “self-documenting code.” I’m a firm believer that the code should be self-explanatory at the surface. Explicit documentation should provide context or improve maintainability.

最后，快速插入所谓的“自文档代码”。 我坚信代码在表面上应该是不言自明的。 明确的文档应提供上下文或改善可维护性。

There are already good articles about this (here’s one), so I won’t go into detail here.

已经有关于这方面的好文章( 这是一篇 )，所以我在这里不做详细介绍。

最后的想法 (Final thoughts)

I hope that you learn from our experience. Our four-layer documentation architecture may not work for you, but it’s important to figure out what will.

希望您能从我们的经验中学到东西。 我们的四层文档体系结构可能不适用于您，但是弄清楚将要做什么很重要。

The big take-aways? First, it’s necessary to develop a healthy understanding of yourself and your own needs before you entangle yourself with a new code base.

外卖？ 首先，在使自己陷入新的代码库之前，有必要对自己和自己的需求有一个健康的了解。

Second, it’s easier to stay out of a bad relationship with legacy code than to extract yourself once you’re already committed.

其次，与遗留代码保持不好的关系要比一旦提交就提取自己要容易得多。

And third, you only leave one legacy. But every commit you make contributes to it. They won’t all be good, they won’t all be bad, but they should at least be clear. Please think about what you’re leaving for those who come after you.

第三，您只留下一份遗产。 但是您所做的每一次承诺都会为它做出贡献。 他们不会全都好，他们不会全都坏，但是至少应该清楚。 请想想那些为您而来的人留下的东西。

Together we can reclaim our legacy as developers.

我们可以在一起重新夺回我们作为开发人员的遗产。

If you enjoyed this article and want more like it, please ? to show your support!

如果您喜欢这篇文章并且想要更多喜欢它，请？ 表示支持！

Jonathan is the Assistant Director of Architecture and Operations at UCLA’s department of Research Information Systems. He earned a Physics degree from Stanford University and has since spent over 10 years working in information systems architecture, data-driven business process improvement, and organizational management. He is also the founder of Peach Pie Apps Workshop, a company that focuses on building data solutions and training for non-profits.

乔纳森(Jonathan)是加州大学洛杉矶分校研究信息系统部门的架构和运营助理总监。 他获得了斯坦福大学的物理学学位，并且在信息系统体系结构，数据驱动的业务流程改进和组织管理方面工作了10多年。 他还是Peach Pie Apps Workshop的创始人，该公司专注于为非营利组织构建数据解决方案和培训。

翻译自: https://www.freecodecamp.org/news/our-team-broke-up-with-instant-legacy-releases-and-you-can-too-d129d7ae96bb/

中断,中断向量,中断向量表