はじめに
社内SEとして既存システムの保守をしていると、しばしば「ブラックボックス化されたシステム」に直面することがあります。本記事では、実際に筆者が対応した、ある会員制Webマイページ機能の改修を通して、ブラックボックスを分解し、明文化していくまでのプロセスを紹介します。
事例：仕様書が存在しないマイページ機能
公開Webサイト上にある会員向けマイページの機能について、ソースコードと最低限の引き継ぎメモのみが残された状態で改修を依頼されました。画面表示・DB構成・ログイン処理など、すべてが一体化しており、改修の影響範囲が全く見えない状況でした。
まずは「見える化」から
最初に行ったのは、コード全体をざっと読み、処理の大まかな流れを手書きのフロー図として書き出すことでした。MVCに近い構造が想定されていましたが、実態はPHPスクリプトの直書きとグローバル変数だらけの設計。処理の流れと画面遷移を可視化し、認知負荷を減らすよう努めました。
UML風の図で自己理解を深める
次に取り組んだのは、クラス図・シーケンス図のような「自分なりのUML」を使って内部構造を把握することです。厳密な記法にはこだわらず、自分が読み返してわかるレベルで設計意図を図にすることを重視しました。図にすることで「何を直すべきか」「どこを分離すべきか」が見えるようになりました。
明文化で再びブラックボックスに戻さない
理解できた内容を、簡潔なフロー図とコメント入りのコードで記録し、将来的に他の人が引き継げるようにしました。また、改修時に触れた仕様や動作についてはMarkdown形式のドキュメントとして社内wikiに残し、改修の履歴も明記しました。
重要なのは「自分だけわかる」からの脱却
一時的にブラックボックスを解明しても、それがまた他人から見えなくなれば意味がありません。常に「未来の他人（あるいは未来の自分）」を意識して、知識の見える化とドキュメントの整備を並行して行うことが重要です。
まとめ
ブラックボックス化したシステムの改修は骨が折れますが、フローの見える化、図による構造把握、そして明文化。この3つのステップを踏めば、再び同じ問題に陥るのを防ぐことができます。社内SEにとって、技術以上に「伝える力」が問われる場面でもあります。
コードを読むのがつらいときってありますよね…。でも「自分のための図」を描いてからは、だいぶ楽になりました！あとでちゃんと残しておけば、また誰かが困らずにすむはずです💡
コメント