引き継いだコードを開いたとき、使われていない処理や古い条件分岐がコメントアウトされたまま残っていることがあります。数行ならまだしも、ファイル全体に散らばっていると、今動いている処理を読むだけでも時間がかかります。
ただ、見た目が悪いからといって一気に削除すると、あとで「なぜその処理を止めていたのか」「この条件は過去の障害対応ではなかったのか」がわからなくなることもあります。
コメントアウトされたコードは実行されませんが、レガシーコードでは過去の判断や制約がそこに残っている場合があります。
この記事では、コメントアウトだらけのコードを整理する前に確認したいポイントを、レガシー対応の実務目線で整理します。
コメントアウトは「不要なゴミ」と決めつけない
コメントアウトされたコードは、基本的には現在の処理を読みづらくします。
実行されないコードが大量に残っていると、読み手は「これはもう不要なのか」「条件次第で戻す予定があるのか」を毎回考えることになります。保守性の面では、早めに整理したほうがよい状態です。
ただし、すべてを同じ扱いで消してよいわけではありません。コメントアウトには、少なくとも次のような種類が混ざります。
- 仕様変更で不要になった旧処理
- 調査中に一時的に止めた処理
- 障害対応で無効化した処理
- 外部サービスや取引先の都合で残した分岐
- 実装者のメモとして残った古いコード
このうち、単なる古いコード片は削除候補です。一方で、障害対応や外部制約に関係するものは、コードとしては不要でも、判断の背景として残す価値があるかもしれません。
大事なのは、コメントアウトを「消すか残すか」の二択で見ないことです。まずは、消すコード、残す理由、別の場所へ移す情報に分けて考えると、整理の判断がしやすくなります。
消す前に見るべき3つの情報
コメントアウトを削除する前に、最低限見ておきたい情報は3つあります。Git履歴、関連チケット、動作確認範囲です。
まずGit履歴です。コメントアウトされた時期、直前の変更、コミットメッセージを見ると、なぜその処理が止められたのかを推測できることがあります。ただし、Git履歴があるから必ず安全とは限りません。コミットメッセージが「修正」「一時対応」だけの場合、そこから十分な理由を読み取れないこともあります。
次に関連チケットや障害対応メモです。コメントアウトの近くにチケット番号、日付、担当者名、取引先名などが残っている場合は、そこから背景を追える可能性があります。特に業務システムでは、コードだけを見ると不要に見えても、過去の運用回避や例外対応として残されたものがあります。
最後に動作確認範囲です。コメントアウトされたコードは実行されていないため、削除しても動作は変わらないように見えます。それでも、周辺のimport、型定義、設定、テストデータ、ビルド設定に影響することがあります。削除後に最低限どの画面、API、バッチ、テストを確認するかは決めておくべきです。
削除前の確認は、次のように軽くチェックリスト化しておくとレビューでも説明しやすくなります。
| 確認するもの | 見る理由 |
|---|---|
| Git履歴 | コメントアウトされた時期と変更理由を探す |
| 関連チケット | 障害対応や業務判断の背景を確認する |
| テスト・動作確認範囲 | 削除後に見るべき影響範囲を決める |
| 周辺コード | import、型、設定だけが残っていないか見る |
どれか一つで判断しきれない場合は、一括削除せず、範囲を絞って進めるほうが安全です。
残すコメントは「理由」が読める形にする
整理していると、削除しないほうがよいコメントも出てきます。たとえば、外部サービスの仕様に合わせた暫定対応、特定顧客だけの例外、次回リリースまでの一時回避などです。
その場合でも、コメントアウトされた古いコードをそのまま残すのは避けたいところです。古い実装を残すより、今のコードに対して「なぜこの形になっているのか」を説明するコメントへ置き換えるほうが読み手に親切です。
悪い例は、次のようなコメントです。
// 旧処理。あとで戻すかも
// const price = calcOldPrice(order)この書き方では、いつ、なぜ、誰が戻す判断をするのかがわかりません。残すなら、理由と参照先を明確にします。
// 外部連携先の税率切替が完了するまで現行計算を維持する。
// 完了条件: ticket-1234 の連携テスト完了後に削除判断する。
const price = calcCurrentPrice(order)残すべきなのは、古いコードそのものではなく、判断の背景です。特にレガシー対応では、コード内にしか残っていない業務知識があるため、消す前に情報の移し先を決める必要があります。
| 状態 | 対応 |
|---|---|
| 古いコード片だけが残っている | Git履歴を確認して削除する |
| 業務上の理由が書かれている | 必要ならコメントを短く書き直す |
| 長い経緯説明になっている | チケットや設計メモへ移す |
| 期限のないTODOになっている | 判断者、期限、参照先を追加する |
コメントは、コードの代わりに仕様を背負うものではありません。コードを読む人が判断に迷うところだけ、短く理由を補うものとして扱うのが現実的です。
整理は小さな差分で進める
コメントアウトが多いファイルを見ると、一気に片づけたくなります。ついでに関数名を直し、重複処理をまとめ、古い分岐も消したくなるかもしれません。しかし、レガシーコードでは「ついで」の変更がレビューを難しくします。
コメントアウト整理の目的は、まず読みにくさを減らすことです。ロジック変更、命名変更、ファイル分割、設計変更を同じ差分に入れると、レビューする側は「本当に動作が変わっていないのか」を確認しづらくなります。
進め方としては、次の順番が安全です。
- まずコメントアウトされた不要コードだけを削除する
- 削除理由や確認範囲をPR説明に書く
- 影響しそうなテストや画面確認を実行する
- 命名変更や構造改善は別の差分に分ける
たとえば、コメントアウトされた旧処理を削除するPRで、同時に関数名変更や条件式の整理まで入れると、差分の意味が混ざります。後から不具合が出たときも、原因が削除なのかリファクタリングなのか追いにくくなります。
一方で、コメントアウト削除だけの小さなPRなら、レビュー観点は明確です。「実行されないコードだけを消しているか」「必要な理由は別のコメントやチケットに残したか」「確認範囲は妥当か」を見ればよくなります。
レガシー対応では、きれいにする速度よりも、戻れる粒度で進めることが大切です。小さく削るほど、判断ミスがあっても影響を追いやすくなります。
同じ状態に戻さないためのルールを決める
一度コメントアウトを整理しても、チームの運用が変わらなければまた増えていきます。急ぎの対応で一時的に処理を止めることはありますが、そのまま残り続けると、数か月後には誰も理由を説明できなくなります。
再発を防ぐには、コメントアウトを禁止するだけでは不十分です。現実には、調査中や障害対応中に一時的に残したい場面があります。そのため、「残すなら何を書くか」を決めておくほうが運用しやすくなります。
たとえば、次のようなルールです。
- 一時的なコメントアウトには理由を書く
- 削除予定日または判断タイミングを書く
- 関連チケットやドキュメントへの参照を書く
- 長い経緯はコード内ではなくチケットに残す
- レビュー時に期限のないコメントアウトを指摘する
このルールがあると、コメントアウトを残すこと自体が悪いのではなく、理由も期限もないまま放置されることが問題だと共有できます。
また、仕様メモをコードに残しすぎないことも重要です。仕様の背景、取引先との合意、障害対応の経緯は、コードコメントよりもチケット、README、設計メモに置いたほうが後から探しやすい場合があります。コードには、今の実装を理解するために必要な最小限の理由だけを残すのがよいでしょう。
まとめ
コメントアウトだらけのコードを整理するときは、すぐに全部消すのではなく、まず中身を分けて見ることが大切です。
不要な古いコードは削除候補です。過去の判断や業務上の制約が含まれているものは、理由を短く書き直すか、チケットや設計メモへ移します。迷う箇所は、Git履歴、関連チケット、動作確認範囲を見てから判断します。
最初にやることは、大きなリファクタリングではありません。1ファイル、または1機能に範囲を絞り、消す・残す・移すの3つに分類することです。その小さな整理から始めるほうが、レガシーコードには安全に向き合えます。
