【ITニュース解説】The Shape Census: Triage a Messy Module Before You Refactor It

システム開発において、長年使われている古いコード、特に「レガシーコード」と呼ばれるような、巨大で複雑、そして誰もその全貌を把握していないモジュールに新しい機能を追加したり、不具合を修正したりする作業は、非常に骨の折れるものです。例えば、900行もある請求書発行機能に、4つのフラグが複雑に絡み合い、おまけにテストコードは誰かが移行作業をした際に動かなくなって以来、ずっと放置されているような状況を想像してみましょう。そこに新しい割引ルールを追加する必要が生じても、そのモジュールを理解していたエンジニアはもうチームにいません。このような時、まずコードを綺麗に整理してから新しいルールを追加しようと直感的に考えがちですが、これこそが、わずか2日で終わるはずだった変更作業を、6週間のバグ修正作業に変えてしまう典型的なパターンなのです。

なぜ「まずコードを読んで整理する」というアプローチが、テストされていない古いモジュールでは失敗に終わるのでしょうか。コードを読むことで、論理的に「何ができるか」は分かります。しかし、実際にユーザーがどのような入力を送り、その結果として「何が実行されているか」は分かりません。この「できること」と「実際に動いていること」の乖離が、リファクタリング時にバグを生む温床となります。例えば、一見使われていないように見えるコードを「デッドコード」と判断して削除してしまうと、実は特定の条件下で重要な役割を果たしていたために、予期せぬ挙動を引き起こすことがあります。また、出力されるデータ（例えば辞書型データ）のどの項目が、後続のシステムにとって必須のデータであるかを、コードを読んだだけでは判断できません。そのため、名前の変更のような些細な修正ですら、他のシステムに破壊的な変更を与えてしまう可能性があります。さらに、コードの構造変更と機能変更を一つの修正としてまとめてしまうと、レビューが非常に困難になり、見落としによるバグのリスクを高めてしまうのです。

このような問題を避けるために、より安全で確実な手順が提案されています。それは、「現在の挙動を正確に記録し、それに基づいて安全な変更を行う」というアプローチです。このプロセスは、以下の4つのステップで構成されます。

まず、最初のステップは「モジュール境界での呼び出し記録」です。これは、変更したいモジュールに関連する関数の「入り口」や「出口」にあたる部分を特定し、そこに「デコレータ」と呼ばれる特別なコードを追加して、その関数がどのような引数で呼び出され、どのような結果を返し、処理にどれくらいの時間がかかったか、といった情報を記録する仕組みです。この記録はJSON形式でファイルに保存されます。例えば、請求書計算関数を呼び出す際に、入力された顧客情報や商品データ、計算された割引額や最終的な請求額、エラーが発生したかどうかといった詳細が、一つ一つの呼び出しごとに記録されるのです。この記録は、実際のテスト実行時やステージング環境での運用時に短期間だけ行い、集めたデータには顧客の個人情報などが含まれる可能性があるため、必ず匿名化やハッシュ化を行い、機密性の高い情報は絶対に外部に持ち出さないよう細心の注意を払う必要があります。

次のステップは、「シェイプの調査」です。記録された数千もの呼び出しデータは、そのままでは人間が全てを読み解くことはできません。そこで、このステップでは、記録されたデータの「値」そのものではなく、「データの構造（シェイプ）」だけを抽出し、分類します。例えば、返り値が「文字列と数値のリストを含む辞書」のような構造であれば、これを一つのシェイプとして識別します。そして、それぞれの関数がどのようなシェイプのデータをどれくらいの頻度で返しているかを数え上げるのです。この調査結果は表としてまとめられ、例えば「ある関数は3種類のシェイプしか返さないが、別の関数は11種類のシェイプを返す」といった情報が得られます。この「シェイプの数」こそが、変更の難易度やリスクを判断する上で非常に重要な指標となります。シェイプの種類が少ない関数は、その振る舞いが比較的シンプルで予測しやすいため、安心して変更に取りかかれるでしょう。しかし、シェイプの種類が多い関数は、内部で複雑な分岐処理が行われている可能性が高く、安易な変更は大きなリスクを伴います。この調査結果に基づいて、どの部分から手をつけるべきか、作業の優先順位を論理的に決めることが可能になります。

三番目のステップは、「記録を特性化テストに変換」することです。ステップ1で収集した実際の呼び出し記録は、現在のシステムがどのような入力に対して、どのような出力を返しているかという「生きた情報」の宝庫です。この記録から、テストコードを自動生成します。このテストは「特性化テスト」と呼ばれ、現在のシステムの振る舞い（意図しないバグも含めて）をそのまま固定する役割を果たします。つまり、テストが成功すれば、現在のシステムと同じ挙動をしていることが保証されるわけです。ただし、タイムスタンプや自動生成されるIDなど、毎回変わる可能性のあるデータは、テストが安定して実行されるように正規化（無視したり、特定の形に丸めたり）する必要があります。これにより、将来コードに変更を加えた際に、特性化テストを実行するだけで、意図せず既存の機能を壊してしまっていないかを瞬時に確認できるようになります。複雑なモジュールであっても、現在の挙動を完全に再現するテストスイートを手に入れることで、自信を持って変更に取り組めるようになるのです。

最後のステップは、「調査結果に基づいて最小限の変更を行う」ことです。これまでの準備によって得られた情報とテストに基づいて、いよいよコードを変更します。この際、いくつかの厳密なルールを守ることが重要です。まず、コードの構造を変えるリファクタリングと、新しい機能を追加する変更は、決して同じプルリクエスト（変更を承認するための提案）に含めず、それぞれ別々に行います。例えば、関数名の変更と、その関数内部のロジック変更は分けて提出するべきです。また、新しい関数などを抽出する際は、ステップ2のシェイプ調査で明確に区別された「シェイプ」を持つ部分から行うようにします。そして、最も重要なのが、変更後に再度シェイプの調査を行い、意図しない形でシェイプの数や種類が変わっていないことを確認することです。もし変化が見られた場合は、一度変更を元に戻すことを検討します。特性化テストがすべて成功し、シェイプの調査結果にも変化がないことを確認できて初めて、その変更は安全であると判断し、マージ（コードベースへの統合）することができます。このプロセスを経ることで、コードの変更によるリスクを最小限に抑え、確実に新しい機能を追加したり、既存のコードを改善したりすることが可能になります。

このアプローチにはいくつかの利点がある一方で、限界も存在します。メリットとしては、何年も手が付けられていなかったような複雑なモジュールでも、現在の挙動を正確に把握し、安全にテストコードを整備できる点です。これにより、闇雲な変更によるバグ発生のリスクを大幅に減らせます。しかし、常にこの方法が適用できるわけではありません。例えば、常に予測不能な挙動をするモジュールや、Pythonの関数呼び出しの範囲外（データベースのトリガーやメッセージキューなど）で主要なロジックが実行されるモジュールでは、このアプローチだけでは不十分な場合があります。また、記録されるデータに個人情報が含まれる可能性があるため、法的なレビューを事前に受ける必要があります。トラフィックが少ないモジュールの場合、十分なデータを収集するのに時間がかかり、プロジェクトの期限に間に合わない可能性もあります。そして、ステージング環境などに記録用のコードをデプロイできないチームでは、そもそもこのアプローチを採用することは困難です。このような場合は、やはり手作業で地道にテストコードを書いていくしかありません。

いずれにせよ、長年の歴史を持つ複雑なモジュールに手を入れる際は、直感に頼るのではなく、データに基づいた慎重なアプローチを取ることが重要です。この手順に従えば、たった一週間のコードリーディングでは決して知り得なかったモジュールの実態を、正確に把握できるでしょう。まずは、シェイプの数が最も少ない、つまり最もシンプルな振る舞いをしている部分から着手し、このデータ主導のアプローチを試してみることをお勧めします。