Javaでプロジェクト開発していると、自分一人ではなくチームで開発しているケースやリリース後の保守についても意識しながら開発する事になります。
仕様によってあるクラスやメソッドを削除したいけど既存で使用している箇所も一部残したいので削除は難しい。。というような場合はクラスやメソッドを非推奨とする「@Deprecated」タグを使用すると便利です。
「@Deprecated」タグを設定する事で今後そのメソッドを他の誰かが使用しようとした際、一目で非推奨というのが読み取れる事が出来ます。
「@Deprecated」タグはパッケージ、クラス、インターフェース、フィールド、メソッド毎に設定可能です。

@Deprecatedタグ：追加前

@Deprecatedタグ：追加後

• 以下の様にメソッド名の箇所に取り消し線が引かれるので、非推奨というのが一目で分かるようになります。

@Deprecated の使い方と注意点

Java のバージョンによる変化

1. @Deprecated アノテーション単体の使用
   古くからある使い方で、メソッドやクラスなどに付与することで「この要素は非推奨・将来削除される可能性がある」という意味を示します。
   ただし、この形だけでは なぜ 非推奨なのか、あるいは代替手段が何かは記載されていないことが多いため、後述する @Deprecated(since = …, forRemoval = …) や Javadoc の併用が望まれます。

2. since と forRemoval 属性付きの @Deprecated
   Java 9 以降では、@Deprecated に属性を追加できるようになりました：

   Java

   @Deprecated(since = "1.5", forRemoval = true) public void oldMethod() { … }

   1 2	@Deprecated(since = "1.5", forRemoval = true) public void oldMethod() { … }

   • since：いつ（どのバージョンで）非推奨になったか

   • forRemoval：将来的に削除される可能性があることを示す（真偽値）
     これによって、将来のリファクタリングやメンテナンス時の判断材料になります。

3. @SuppressWarnings("deprecation") の活用
   非推奨なコードをあえて使う（たとえば後方互換性のため）場合、呼び出し元には警告（deprecated 警告）が出ます。これを抑制したい場合に、@SuppressWarnings("deprecation") を使うことがあります。ただし濫用は推奨されません — 抑制する場合、なぜ抑制するのか明示をコメントなどで入れておくとよいでしょう。

Javadoc における記述

• @deprecated タグ（小文字）を Javadoc に書く
  例：

  Java

  /** * @deprecated こちらのメソッドは非推奨です。代わりに {@link #newMethod()} を使ってください。 */ @Deprecated public void oldMethod() { … }

  1 2 3 4 5

  /** * @deprecated こちらのメソッドは非推奨です。代わりに {@link #newMethod()} を使ってください。 */ @Deprecated public void oldMethod() { … }

  Javadoc の @deprecated タグでは、理由 や 代替手段 を書くのがベストプラクティスです。将来メンテナが見たときに「なぜこのメソッドを使ってはいけないか」「使うなら代替は何か」がすぐわかるようにしておくとよいです。

• @see や {@link …} を併用して、代替メソッドや関連クラスへの参照を明示することが望ましいです。

実践上の注意点・ベストプラクティス

1. 非推奨は “すぐ削除” を意味しない
   非推奨にしたからといってすぐ削除してよいわけではありません。特に公開 API やライブラリでは互換性を保つ必要があるため、非推奨 → 廃止 → 削除のステップを段階的に行うことが多いです。

2. 非推奨にするタイミングとコミュニケーション
   非推奨にする際は、リリースノートやドキュメントでユーザーに通知したり、マイグレーションガイドを提供したりすることが望まれます。単に @Deprecated をつけただけだと、他の開発者が意図を見逃す可能性があります。

3. テストと静的解析ツールとの関係

   • テストコード内で非推奨 API を使っていると、警告が出る場合があります。必要に応じてテストコードにも @SuppressWarnings("deprecation") を書くか、テスト対象を変更するか検討します。

   • 静的解析ツール（たとえば SonarQube や IDE の警告機能など）によって、非推奨 API の利用を検出し、代替 API を使うように促されるケースがあります。

4. 非推奨対象の範囲を最小限にする
   公開 API・ライブラリでは、できるだけ影響範囲を限定して、非推奨とするクラス・メソッドを絞るのが望ましいです。広く使われている機能を急に非推奨にすると、利用者に負荷をかけてしまいます。

5. 段階的廃止 (deprecation → removal) のスケジュール設計
   非推奨化してから削除までの猶予期間（複数バージョン）を取ることが慣例です。期間中は警告を出すのみとし、最終的に削除する際には major バージョンアップで行うとよいでしょう。

6. 互換性 (backward compatibility) の観点
   非推奨にした API を内部で使い続けている場合、将来的に削除したときに影響範囲が広くなることがあります。内部実装も可能な限り、代替 API へ移行しておくべきです。

実例：非推奨化と移行

このようにラップしておくと、既存コードとの互換性を保ちつつ、利用者側が徐々に processV2 に移行しやすくなります。

補足

• 単に @Deprecated を付けるだけでなく、理由と代替手段をドキュメントに記載すべき。

• Java 9 以降では since／forRemoval 属性が使える。

• 非推奨化 → 廃止 → 削除を段階的に設計するべき。

• 利用者・メンテナに対する周知 (ドキュメント、リリースノート、マイグレーションガイド) を欠かさない。

• 静的解析ツールや IDE が出す警告を活用して、非推奨 API の利用を検出・移行を促す。