フロントエンドの戦場で日々コードを書き殴っていると、避けて通れないのが「技術的負債」の整理整頓だ。
「この古いユーティリティ関数、誰も使ってないはずだけど、もしかしてどこかのレガシーな画面でまだインポートされてる……？」
「新しい設計のAPIに移行したいのに、古い関数を削除したらどこでバグるか怖くて夜しか眠れない」
こういう恐怖、中級に差し掛かったエンジニアなら一度や二度は経験しているはずだ。チームが大きくなり、コードベースが肥大化するほど、この「負債の安全な返済」は難易度を増していく。
そこで今日、君たちに授けたいのが JSDocの `@deprecated` タグ を使った、モダンかつスマートな非推奨警告のテクニックだ。
TypeScriptを導入しているプロジェクトなら言うまでもないが、実は素のJavaScript（JSDoc）環境であっても、現代のIDE（VS Codeなど）やビルドツールは、このタグを神のように忠実に解釈して警告を出してくれる。ブラウザの実行エンジン自体が特別な処理をするわけではないが、「開発時のエディタ上」で強力な心理的プレッシャーと物理的な警告を与えてくれるのがミソなのだ。
現場で明日から使える実践的なアプローチを、私の経験を交えて解説しよう。
—
なぜ `@deprecated` なのか？ 現場の泥臭い課題解決
いきなり関数を消す。これはジュニアがやりがちで、シニアが最も頭を抱える「やってはいけない爆弾投下」の筆頭だ。リファクタリングは段階的に行わなければならない。
1. フェーズ1（周知）: 「この書き方は古いから、こっちの新機能を使ってね」と伝える。
2. フェーズ2（猶予）: 一定期間、古い書き方も動くように残しつつ、警告を出し続ける。
3. フェーズ3（排除）: 誰も使わなくなったことを確認して、コードを墓場に送る。
この「フェーズ1と2」を自動化し、開発者の目に強制的に飛び込ませるための特効薬が `@deprecated` だ。これをサボってSlackで「〇〇関数消したんで！」と言っても、誰もドキュメントなんて読まない。コードが語るようにするのが、プロのアーキテクチャだ。
—
実践！ JSDoc `@deprecated` の基本と書き方
まずは、プレーンなJavaScript（あるいはJSDocを効かせたJSファイル）での具体的な実装を見てみよう。
/
- ユーザーのフルネームを取得する（レガシー版）
- @deprecated この関数はバージョン2.0で廃止予定です。
- 代わりに `getUserFullNameAsync` を使用してください。
- @param {Object} user – ユーザーオブジェクト
- @param {string} user.firstName – 名
- @param {string} user.lastName – 姓
- @returns {string} 結合されたフルネーム
- @example
- // 悪い例（警告が出ます）
- const name = getOldFullName({ firstName: ‘Taro’, lastName: ‘Yamada’ });
/
export function getOldFullName(user) {
// 内部でこっそりコンソールに警告を出す親切設計にするのも手
console.warn(‘DEPRECATED: getOldFullName は非推奨です。新しいAPIへ移行してください。’);
return `${user.firstName} ${user.lastName}`;
}
このコードをVS Codeなどのエディタで読み込み、別のファイルで `getOldFullName` を呼び出してみるとどうなるか。関数名に取り消し線（打消し線）がスーッと入り、マウスホバーした瞬間に「非推奨です」という警告メッセージがポップアップとして画面に鎮座する。
さらに、TypeScriptの型チェッカー（`allowJs: true` やJSDocの型推論）が有効であれば、ビルド時や型チェック時にも検知させることが可能だ。
—
もう一歩進んだ実務的テクニック：移行パスの提示とカスタムメッセージ
単に「古いよ」と怒るだけの警告は、ただのストレスだ。優秀なエンジニアは、「次にどうすべきか」の道筋（移行パス）を必ずセットで提示する。
以下のサンプルを見てほしい。オブジェクトのプロパティや、定数に対しても `@deprecated` は有効に機能する。
/
- @typedef {Object} NewUser
- @property {string} first
- @property {string} last
/
/
- 現代的なユーザー名フォーマッター
- @param {NewUser} user
- @returns {string}
/
export function formatUserName(user) {
return `${user.last}, ${user.first}`;
}
/
- @deprecated
- 旧フォーマットのオプション設定オブジェクト。
- 代わりに `formatUserName` の引数構造体を直接渡してください。
/
export const LEGACY_CONFIG = {
separator: ‘ ‘,
order: ‘first-last’
};
このように、関数だけでなく定数や設定オブジェクトそのものに `@deprecated` を付与することで、「その設定自体がもうオワコンである」という事実を開発者に突きつけることができる。
—
ブラウザの裏側と開発者体験（DX）の裏話
ここで少し、JavaScriptのランタイム（ブラウザやNode.js）が裏側でどう動いているかについても触れておこう。
勘の良いエンジニアなら、「これ、実行時にエラーになるの？」と疑問に思うかもしれない。答えは 「ノー（何もしない）」 だ。
JavaScriptエンジン（V8など）は、JSDocのコメント（`/ … /`）をパースこそすれ、実行時には単なるコメントとして完全に無視する。ブラウザのメモリ上では、このアノテーションは存在しないものとして扱われる。
つまり、`@deprecated` は「実行時エラーを起こすためのものではなく、開発体験（DX）を爆上げし、チームの負債蓄積を防ぐためのビルド・エディタ層のガバナンスツール」なのだ。
TypeScriptや最新のIDEが普及した現代において、私たちは「動くコードを書く」だけでなく、「壊れにくく、メンテナンスしやすいコードをチーム全体で維持する」責任がある。そのための強力な武器の一つが、このJSDocを活用したアノテーションなのだ。
—
シニアからのまとめ・アドバイス
明日からチームの開発に取り入れるためのステップをまとめる。
1. 既存のレガシーコードをすぐに消さない: 消す勇気も大事だが、まずは `@deprecated` をつけて警告を出すことから始めよう。
2. 必ず代替案（代替関数やプロパティ）をコメントに書く: 「使うな」だけではエンジニアは路頭に迷う。「こっちを使え」というリンクや名前を必ず添えること。
3. チームでルールを共有する: PR（プルリクエスト）のレビュー時に、古いコードを書く後輩がいたら「ここに `@deprecated` つけようか」「あるいはもう新しい方に書き換えちゃおうか」と導いてあげること。
コードベースは生き物だ。放置すればゴミ屋敷になり、手入れをすれば美しい庭になる。
地味なテクニックだが、こういう細部の積み重ねが、君を「頼れるシニアエンジニア」へと押し上げてくれるはずだ。さあ、明日のPRから早速使ってみてくれ。
コメント