文書のないコードから、次の開発の基準を見つける: アーティストプラットフォームの引き継ぎ検証

コードがあることと、基準があることは違いました

文書のないサービスでは、現在の動作と必要な動作が容易に混ざります。画面にどんな結果が出ていても、それが意図された機能なのか修正すべき問題なのかを判断しにくいことがあります。

だからといって、現在のコードをそのまま要件とすることもできません。既存の実装をたどればサービスがどう作られたかは分かりますが、その実装が利用者に必要な結果まで保証するわけではないからです。

したがって引き継ぎ検証には二つの作業が必要です。現在の動作を説明することと、その動作を評価する基準を用意することです。文書の不在は引き継ぎの不便にとどまらず、検証の出発点にも影響します。

画面からAPIとデータ構造までさかのぼりました

プロジェクトではコードを読み、画面、API、データ構造を追跡して機能単位で内容を整理しました。実装結果をさかのぼって構造と動作を把握する、リバースエンジニアリングの方法です。

画面は利用者が見る結果を示します。APIはその動作を処理する経路であり、データ構造は結果が残る形を示します。このつながりを併せて見てはじめて、画面一つでは表れない関係を理解できます。

復元した文書の価値は、分量よりも問いに答えられるかにあります。どの機能がどの動作とつながっているかを探せてこそ、修正前に見るべき範囲も決められます。

この段階は、過去の設計者の意図をすべて解明したという意味ではありません。確認できる実装と動作をもとに、以後の検証と開発が参照する説明を作った作業です。

文書に整理した内容を実際の動作と突き合わせました

整理した機能を基準に、全体的な機能検証を行いました。見つかった欠陥には重大度を付けて記録し、検証結果を文書とともに残しました。

文書化とテストを別々に考えると、文書は説明資料として、テストは一回限りの点検として終わりがちです。二つの作業がつながれば、説明した機能が実際にどう動いたかを確認できます。

特に引き継ぎのプロジェクトでは、既存コードが存在するという理由でその動作を正解として扱わないことが重要です。利用者が体験する結果と機能の判断基準が食い違っていないかを、別に見る必要があります。

この事例で検証は、コードを読んだという確認にとどまりませんでした。整理した内容を実行で確かめ、以後の修正で再び参照できる記録として残しました。

ポイント機能も既存の取引とつなぐ必要がありました

既存の構造を把握して検証したあと、ポイントのチャージ・管理機能を開発しました。チャージ、利用、残高の関係を整理して既存のサービスにつなぎました。

ポイント機能は、金額のように見える数字を一つ追加する仕事ではありません。残高が変わったなら何によって変わったのかを説明できなければならず、利用の動作は既存サービスの取引とかみ合う必要があります。

たとえば画面に残高が表示されていても、どの利用履歴がその結果を作ったのか分からなければ、運用者は問い合わせに対応しにくくなります。こうした理由から、新規機能を既存の構造と切り離して考えることは難しいのです。

A社の事例では、まず理解して検証した基盤の上に機能を加えました。構造を知らないまま追加開発だけを急ぐアプローチとの違いはここにあります。

次の担当者に、コード以外の資産を残しました

プロジェクトの成果には、機能を説明する文書、テスト資産、欠陥記録が含まれました。追加機能とともに、次の担当者がサービスを理解するために必要な資料を残したのです。

こうした資料があれば、保守の問題がすべて自動的に解決するわけではありません。以後に機能が変われば、文書と検証基準も一緒に更新しなければなりません。ただ、次の作業が何の説明もないコードから再び出発しないようにはしてくれます。

この事例で重要な変化は、新しい文書を作ったという事実よりも、引き継いだサービスについて問いを立て、その答えを確認できるようになったことです。

ソフトウェアの引き継ぎは、ファイルを受け取った瞬間に終わるものではありません。何を受け取ったのかを理解し、変えるときにどの影響を確認すべきかを説明できたとき、次の開発が始まります。