仕様書を作ってほしい、と頼まれる。元になる資料は無く、あるのはコードと動いている本番環境だけ。期限は一か月。この依頼を受けたとき、最初にやってはいけないのは、リポジトリの先頭から読み始めることです。
十万行のコードを全部読んで仕様に起こす作業は、物理的に終わりません。仮に終わったとしても、出てくるのはコードを日本語に置き換えただけの文書で、読む人がいない。書き起こすべき場所は決まっています。分岐と、外部とのやり取りです。
何のための仕様書かを先に決める
読む範囲は、使い道で変わります。置き換えの見積もりに使うのか、運用担当者が障害時に参照するのか、監査で提出するのか。この三つは別物で、同じ文書では兼ねられません。
依頼者に聞いても「とりあえず全部」と返ってくることがあります。そのときは、できあがった仕様書を誰が最初に開くかを聞きます。置き換えを担当する開発会社が開くなら、データの構造と外部連携が要ります。運用担当者が開くなら、エラーが出たときにどこを見るかが要ります。開く人が決まれば、読まない場所が決まります。
ここを決めずに始めると、一か月後に「これでは使えない」と言われます。書き直す時間はもうありません。
外部との境界を先に固める
コードを開く前に、このシステムが外と何をやり取りしているかを一覧にします。他社のAPIを呼んでいる、FTPにファイルを置いている、メールを送っている、決済代行に投げている。受ける側も同じで、外から叩かれるエンドポイント、取り込んでいるCSV、連携先から届くWebhook。
ここを先にやる理由は二つあります。一つは、外部連携が仕様の中で最も変えられない部分だからです。相手先の都合で動いているので、こちらが置き換えるときも形を保つ必要がある。もう一つは、量が有限だからです。内部のロジックは読み出すときりがありませんが、外部との接続点は数えられます。十も二十もあれば多いほうです。
探し方は、HTTPクライアントの初期化、SMTPの設定、ファイル転送のライブラリ、接続先のホスト名が書かれた設定ファイル。この四つを横断検索すれば、だいたい拾えます。拾ったら、呼び出し元を一段だけ辿って、どの業務から出ている通信かを書き留めます。深追いはしません。
つまずくのは、設定ファイルに書かれている接続先が本番で使われているとは限らない点です。テスト用の向き先が残っていたり、環境変数で上書きされていたりする。本番の設定を確認できないまま仕様書に書くと、そこだけ事実と違う文書になります。確認できなければ「要確認」と書いて残します。
分岐だけを読む
内部のコードに入るときは、条件分岐を探して読みます。業務の仕様は分岐に溜まっているからです。
特定の取引先コードだけ手数料の計算が違う。月末日は締め処理の判定が変わる。ある日付より前に登録された会員は旧料金で計算する。こういう条件が仕様の中身で、正常系の処理はどのシステムでも似たような形をしています。正常系を丁寧に書き起こしても、読む人は得をしません。
分岐を読むときは、条件式に出てくる値をそのまま書き写します。マジックナンバーが入っていたら、その数字を書きます。意味を推測して「優良顧客の場合」などと言い換えると、あとで事実として扱われて誤りが広がります。意味が分かるのは、関係者に聞いたときだけです。聞けないなら、条件式のまま残して不明と添えます。
分岐のうち、どれを書くかにも線を引きます。入力値の検証、nullチェック、権限の確認。この種の分岐は数が多いわりに、業務の仕様をほとんど含みません。まとめて「一般的な検証処理」として一行で済ませ、業務上の条件だけを個別に書きます。
読まないと決めたものを書いておく
自動生成されたコード、フレームワークが用意した雛形のまま使われていないファイル、コメントアウトされた大きな塊、過去のバージョンが丸ごと残っているディレクトリ。これらは読みません。
ただし、読まなかったことは仕様書に書きます。どのディレクトリを対象外にしたか、なぜ対象外にしたかを一節だけ設けて残しておく。これが無いと、仕様書を受け取った側は全部を調べた結果だと思い込みます。置き換えの見積もりがそのまま狂います。
判断に迷ったものも、同じ場所に書きます。使われているかどうか分からないバッチが三本ある、という一行があるだけで、次に調べる人の時間が変わります。
コードから読み取れないもの
コードに書いていないことがあります。なぜその分岐が入ったのか、その数字はどこから来たのか、この処理はいつまで必要なのか。理由と期限は、コードには残りません。
手を動かす範囲で埋められるのは、コミットログと課題管理システムの履歴です。分岐を追加したコミットのメッセージに、チケット番号が残っていることがある。追えるなら追います。追えなければ、そこで止めます。
運用でしか分からないこともあります。仕様上は毎日動くバッチが、実際には担当者が手で止めている日がある。コードを読んでも出てきません。こういう食い違いは、運用担当者に半日もらって聞くほうが早い。コードを読み続けても出てこないものを、コードから出そうとしないことです。
この段階でやらなくていいこと
画面項目の一覧を作る作業は、後回しにできます。項目名と桁数を並べた表は作るのに時間がかかるわりに、置き換えの判断材料にはなりません。必要になったら、そのときに画面を開いて書けばいい。
処理フロー図も、急いで作る必要はありません。図にすると分かった気になりますが、分岐の条件が図から落ちます。落ちた条件が、置き換えで問題になる部分です。
書き起こしが進まないときは、対象を狭めます。システム全体ではなく、売上に直結する一つの業務だけを最後まで書く。一本通した文書があれば、残りをどのくらいの労力で書けるかが見積もれます。全体を浅く撫でた文書からは、それが分かりません。
