Introduction

Marking a class as deprecated is how you tell other developers, the compiler, and your future self that the type should no longer be used for new code. In Java, the correct approach is not just adding one annotation; the class should also explain what to use instead and whether removal is planned.

Use @Deprecated on the Class

At the Java language level, a deprecated class is marked with the @Deprecated annotation.

1package example;
2
3/**
4 * @deprecated Use ModernReportClient instead.
5 */
6@Deprecated(since = "2.4", forRemoval = true)
7public class LegacyReportClient {
8    public String fetch() {
9        return "legacy result";
10    }
11}

Three parts matter here:

• '@Deprecated tells the compiler and IDE that the class is obsolete.'
• 'since = "2.4" records when you deprecated it.'
• 'forRemoval = true tells callers that you intend to remove it in a later release.'

The annotation alone produces warnings in consuming code, which is useful because callers see the warning exactly where they still reference the old API.

If you compile code that still uses the class, Java reports a deprecation warning:

1package example;
2
3public class Demo {
4    public static void main(String[] args) {
5        LegacyReportClient client = new LegacyReportClient();
6        System.out.println(client.fetch());
7    }
8}

Compile with lint warnings enabled:

javac -Xlint:deprecation example/*.java

That gives you build-time visibility instead of relying on humans to notice a release note.

Add the Javadoc @deprecated Tag

A good deprecation includes migration guidance, not only a warning marker. In Java, the conventional place for that guidance is the Javadoc @deprecated tag.

1/**
2 * @deprecated Use {@link ModernReportClient} because it supports retries
3 * and structured error handling.
4 */
5@Deprecated(since = "2.4", forRemoval = false)
6public class LegacyReportClient {
7}

The Javadoc tag is important because it answers the practical question every caller has: "What should I use instead?"

If you leave out the replacement path, you force every consumer to inspect source code or issue trackers to guess the migration target. That slows upgrades and increases the chance that teams keep using the deprecated class for another year.

Provide a Replacement Class

Deprecation works best when the alternative is already available and easy to adopt.

1package example;
2
3public class ModernReportClient {
4    public String fetch() {
5        return "modern result";
6    }
7}

A small migration example makes the intent obvious:

1package example;
2
3public class Demo {
4    public static void main(String[] args) {
5        ModernReportClient client = new ModernReportClient();
6        System.out.println(client.fetch());
7    }
8}

This pattern keeps the warning actionable. A deprecation without a replacement is often just a delayed breaking change.

Decide Whether forRemoval Should Be True

forRemoval = true is a strong signal. Use it when you have a real removal plan and have confirmed that downstream users have time to react.

If you only want to discourage new usage but cannot remove the class soon, keep the deprecation but set forRemoval = false.

1/**
2 * @deprecated Scheduled to be replaced, but still supported for the 2.x line.
3 */
4@Deprecated(since = "2.4", forRemoval = false)
5public class LegacyReportClient {
6}

That distinction matters in libraries. Build tools, IDEs, and static analysis treat a pending removal more seriously, so setting it too early creates noise and unnecessary pressure.

Deprecation Is an API Contract, Not a Comment

Once a public class is deprecated, treat that decision as part of the API lifecycle. Keep the deprecation note accurate, mention it in release notes, and verify that examples and tests no longer teach the old type.

A practical rollout often looks like this:

1. Add the replacement class.
2. Mark the old class with @Deprecated and Javadoc guidance.
3. Update internal usages and documentation.
4. Wait at least one stable release cycle.
5. Remove the class only when callers have had a realistic migration window.

That sequence is much safer than deprecating and removing in the same release.

Common Pitfalls

• Using @Deprecated without a Javadoc @deprecated message that names the replacement.
• Setting forRemoval = true even though the class will remain for several major releases.
• Deprecating a class while tutorials, tests, or sample code still depend on it.
• Forgetting to enable compiler warnings, so the team never notices continuing usage.
• Deprecating a public class before the replacement API is stable enough for real workloads.

Summary

• Mark a Java class with @Deprecated.
• Add a Javadoc @deprecated tag that explains the migration path.
• Use since to record when the change happened.
• Set forRemoval only when removal is genuinely planned.
• Make deprecation useful by shipping a clear replacement and updating examples to match.