コーヒーブレイク #20。レガシー コードとは何か、またそれをどのように扱うか。技術文書の作成を容易にするツール

レガシーコードとは何か、そしてそれをどのように扱うか

出典: Dou 遅かれ早かれ、プログラマーはレガシー コードに遭遇することになるでしょう。この知人の影響を和らげるために、私は私自身の経験、特にレガシー Java システムでの作業からいくつかの実用的なヒントと例を選択しました。

従来の機能

レガシーは他人のコードであり、多くの場合非常にひどいため、どのように操作するかが明確ではありません。また、レガシー システムを使用する必要がある場合は、古いコードに加えて、次のような問題も発生します。

• 時代遅れのテクノロジー。
• 異種混合アーキテクチャ。
• 文書が欠如している、または完全に欠如している場合もあります。

実際、レガシー コードはそれほど怖いものではありません。その理由は次のとおりです。システムが 10 年間存続し、まだ動作しているのであれば、ある程度の用途はあります。もしかしたら、（前回のスタートアップとは違って）かなりの収益を上げているかもしれません。さらに、このコードがこれほど長期間実稼働環境で存続できた場合、このコードは比較的信頼性が高くなります。したがって、変更は慎重に行う必要があります。まず最初に、次の 2 つのことを理解する必要があります。

1. 私たちは、1 日に何百万もの利益を上げたり、何千人もの人々がアクセスしたりするシステムを軽視することはできません。どれほど稚拙に書かれていたとしても、この不快なコードは運用環境まで生き残り、24 時間年中無休で動作します。

2. このシステムは実際のお金をもたらすため、これを扱うことには大きな責任が伴います。これはスタートアップではありませんが、ユーザーが明日から取り組むものです。これは、エラーの代償が非常に高いことも意味しており、ここでのポイントはクライアントの主張ではなく、実際の状況にあります。

リバースエンジニアリング

レガシー コードを正常に操作するには、リバース エンジニアリング手法を使用する必要があります。まず、コードを注意深く読んで、その仕組みを正確に理解する必要があります。ドキュメントがない可能性が高いため、これは必須です。著者の思考の流れを理解していないと、変更を加えてしまい、予期せぬ結果を招くことになります。これから身を守るには、隣接するコードを詳しく調べる必要もあります。そして同時に、幅だけでなく深さにも動きます。エラーが発生したメソッドが呼び出された場所はどこですか? それを呼び出すコードはどこから来たのでしょうか? レガシー プロジェクトでは、「呼び出し階層」と「型階層」が何よりも頻繁に使用されます。デバッガを使用するには、まずエラーを見つけるために、そして次にすべてがどのように機能するかを理解するために多くの時間を費やす必要があります。記録に関しては、産業考古学に頼るのも悪くありません。どこかにある古いドキュメントを掘り出し、あなたが継承したコードがどのように書かれたかを覚えている人に話すことは非常に役立つ場合があります。これらのテクニックを使用すると、遅かれ早かれ、コードをある程度理解できるようになります。ただし、努力が無駄にならないように、調査結果をすぐに文書化する必要があります。これを行うには、ブロック図またはシーケンス図を描くことをお勧めします。もちろん、怠け者になるでしょうが、これは必ず実行する必要があります。そうしないと、ドキュメントなしで 6 か月以内に、初めてのときのようにこのコードを掘り下げることになります。

コードを書き直さないでください

開発プロセスで最も重要なことは、時間内に自分を追い詰めることであり、コード全体を最初から書き直そうとしないことです。これに必要な工数を見積もってください。顧客が、既に機能しているものをやり直すのにそれほど多額の費用を費やしたいとは考えにくいです。これはシステム全体だけでなく、システムのどの部分にも当てはまります。もちろん、すべてを理解するのに 1 週​​間、何かを修正するのにさらに 1 週​​間かかる場合もあります。しかし、システムの一部を再度作成するために 2 か月の猶予を与える可能性は低いです。代わりに、コードの残りの部分と同じスタイルで新しい機能を実装します。言い換えれば、コードが古い場合は、新しい美しいテクノロジを使用する誘惑に駆られるべきではありません。そのようなコードは非常に読みにくくなります。たとえば、システムの一部が Spring MVC で書かれ、一部が裸のサーブレットで書かれているというような状況に遭遇する可能性があります。そして、サーブレットで書かれた部分に何か他のものを追加する必要がある場合は、同じ方法でサーブレットに追加します。

ビジネス上の利益を尊重する

すべてのタスクは、まず第一に、ビジネスの価値によって決定されることを覚えておく必要があります。ビジネスの観点から特定の変更が必要であることを顧客に証明しなければ、そのような変更は行われません。そして、顧客を説得するには、顧客の立場に立って、顧客の利益を理解するように努めなければなりません。特に、コードが読みにくいという理由だけでリファクタリングを行うことは許可されず、それに耐えなければなりません。どうしても耐えられない場合は、静かに少しずつコードを再編成し、作業をビジネス チケット全体に分散することができます。あるいは、これにより、たとえばエラーの発見に必要な時間が短縮され、最終的にはコストが削減されることを顧客に納得させます。

テスト

どのプロジェクトでもテストが必要であることは明らかです。ただし、レガシー システムを使用する場合は、行われた変更の影響が常に予測できるとは限らないため、テストにも特別な注意を払う必要があります。少なくとも開発者と同数のテスターが必要です。そうでない場合は、自動化が非常に得意である必要があります。私たちのプロジェクトでは、テストは次のフェーズで構成されていました。

1. 検証。機能の実装された機能が別のブランチでチェックされる場合。
2. 安定化。すべての機能がマージされたリリース ブランチがチェックされるとき。
3. 認定。ハードウェアの特性と構成の点で実稼働環境に可能な限り近い認定環境で、わずかに異なるテスト ケースで同じものが再度実行される場合。

そして、これら 3 つのフェーズをすべて経た後にのみ、リリースを行うことができます。おそらく、安定化段階ですべてが明確になっているため、認証は追加の段階であると考える人もいるでしょう。しかし、私たちの経験から、そうではないことがわかります。別のマシンで 2 番目のラウンドとして実行される回帰テスト中に、何らかの理由で何かが起こることがあります。それが出てくるでしょう。

DevOpsを正式化してリリースする

解放手順は、例えば次のようになります。開発が完了し、2 つまたは 3 つのテスト フェーズが完了すると、リリース予定時刻の 36 時間前に DevOps チームに電子メールを送信します。この後、devops チームに電話し、環境に対するすべての変更について話し合います (データベースと構成のすべての変更についてチームに通知します)。変更ごとにドキュメント (Jira のチケット) が作成されます。そして、リリース中に、これに関係する全員が集まり、全員が今何をしているかを言います。「データベースをアップロードしました」、「これこれのサーバーを再起動しました」、「本番環境で回帰テストを実行しました。」 」何か問題が発生した場合、元のリリース文書に正確に記載されているリリースのロールバック手順が開始されます。そのような文書がなければ、間違いなく何かを忘れたり、混乱したりするでしょう。

コードの品質を制御する

最後に、コード レビューは、何らかの理由ですべてのプロジェクトで使用されているわけではありません。すべてのコードが複数の人によってレビューされるのは素晴らしいことです。非常に強力なチームであっても、コードレビューのプロセスでは必ずいくつかのバグが発見され、それを複数人で確認すると、特定されるバグの数は増加します。さらに、場合によっては 3 人目、4 人目の査読者が最悪の点を見つけることもあります。

技術文書の作成を容易にするツール

出典: Dzone ほとんどのプログラマーは技術文書を書くのが好きではありません。心理学の専門家であるジェラルド・ワインバーグは、ドキュメントを「プログラミングのヒマシ油」とさえ呼びました。開発者はドキュメントを読むのは好きですが、自分で書くのは単純に嫌いです。 ガイダンスが不足していたり​​、ロードマップが空白であると、ソフトウェアのさまざまな部分がどのように動作するかについての情報が不足します。これは、ドキュメントが存在しない場合、製品の正確さと有用性を信頼できないため、最終的にコードのエンド ユーザーのエクスペリエンスを悪化させます。プログラマーがドキュメントを書く習慣を身につけやすくするために、現在ほぼすべての人が利用できる 4 つの優れたツールに注目することをお勧めします。

GitHub ページ

おそらく今日、GitHub での作業経験のない開発者は一人もいないでしょう。また、ドキュメントを保存する場所が必要なプログラマーにとっても最適な場所です。多くの人はコードベースで標準の Readme を使用して、ユーザーに簡単なハウツー ガイドを提供しますが、これが GitHub でドキュメントを作成する唯一の方法ではありません。GitHub Pagesを使用すると、ドキュメントやチュートリアルなど、プロジェクトのページをホスティングするだけではありません。すべての GitHub リポジトリと直接対話できるため、開発者はコードを更新するのと同じ方法でドキュメントを更新できます。さらに、ここではJekyllを使用できます。マークアップをプレーン テキストまたは本格的な Web ページに変換するのに役立ちます。

ドキュメントを読む

名前が示すように、Read the Docs は開発者にドキュメントを保存および閲覧するためのプラットフォームを提供します。このサービスは GitHub Pages とよく似た仕組みで、プログラマは Git、Bazaar、Mercurial などのお気に入りのバージョン管理システムからドキュメントを変更できます。自動バージョン管理とページ作成もサポートされています。Read Docs の最も優れている点は、その柔軟性です。Webhook をサポートしているため、ドキュメント作成プロセスの多くを自動化できます。これにより、ほとんどのプログラマが関わりたくないタスクの時間を大幅に節約できます。さらに、プラットフォーム上でホストされているすべてのコンテンツは、PDF、単一ページの HTML、さらには電子書籍形式など、さまざまな形式で一般に公開されています。このサービスは、ドキュメントを最新の状態に保つための日常作業の重要な部分を引き受けます。

テトラ

Tettra は、ソフトウェア ドキュメントを保存するための単なるプラットフォームではなく、完全なナレッジ ベースです。これは、プロジェクトにさまざまなソフトウェアを開発する大規模なコーダー グループが含まれる場合に特に効果的です。Tettra を使用すると、一般的な質問に対する回答を文書化できます。

養蜂場

Apiaryが開発者にとって非常に役立つのは、API ドキュメントの作成に非常に役立つという事実です。このプラットフォームを使用すると、ユーザーは模擬 API 呼び出しを含むドキュメントをMarkdownで作成できます。Apiary では、API 要素のテストとプロトタイプの作成も可能です。言い換えれば、これはドキュメント ツールとテスト プラットフォームが 1 か所にまとめられたものです。