How to Safely Deprecate an Old Apex Class

Open your list of Apex Classes in Salesforce Setup. Start scrolling. As you get past the classes you work on every day, you start to see them, lurking in the digital shadows.

OldBillingUtils_2018.cls
ProcessLeads_V2_DEPRECATED.cls
TempContactFix_DoNotUse.cls

Your org is haunted by digital ghosts—classes that you think are no longer used, but you're too nervous to delete. What if it's called by some obscure, once-a-year process? What if a critical report depends on it?

This digital hoarding isn't harmless. Unused code adds clutter to your org, slows down deployments, confuses new developers, and creates a genuine risk that someone might accidentally use an old, buggy piece of logic.

Deleting code can be more stressful than writing it. But with a safe, methodical process, you can confidently clean up your org, reduce your technical debt, and make your codebase a better place for everyone. This guide will show you how.

Step 1: The Investigation - Is It Truly Unused?

This is the most critical phase. You cannot proceed until you have done the detective work to prove the code is no longer in use. A single missed reference can lead to a production failure.

Action 1: The Simple First Step

In the Apex Classes list view, find your target class and click the "Where is this used?" button. This is a great starting point and will find any static references in other Apex classes, triggers, and Visualforce pages. But be warned: this is not enough.

Action 2: The Intelligent Code Search

The standard "Where is this used?" button has blind spots. It often fails to find dynamic Apex references (e.g., Type.forName()) and, more importantly, it won't find references from declarative tools. This is where you need a more powerful search tool.

Using a semantic search tool like Kodelens is a game-changer here. First, search for the class name itself to find references the standard tools might miss. But the real power comes from searching for the concept the class handled. For example, if you're trying to deprecate OldLeadProcessor.cls, ask Kodelens:

"Show me where lead processing is handled."

If the results consistently point to a new system (like NewLeadService.cls) and your old class is nowhere to be found, that's strong evidence it has been successfully replaced.

Action 3: The Declarative Deep Dive

Finally, you have to manually check for references in the "clicks, not code" parts of your org. Look for your class name in:

• Flows that use "Call Apex" actions.
• Legacy Process Builders that call Apex.
• Custom Buttons that execute JavaScript, which in turn might call your Apex class.

Step 2: The Soft Deprecation - Commenting Out

You've done your investigation and you're 99% sure the class is unused. Your next instinct might be to hit "Delete." Resist that urge.

Action 1: Rename the Class

First, rename the class by appending _DEPRECATED_YYYYMMDD to its name (e.g., OldLeadProcessor_DEPRECATED_20251030.cls). This acts as a clear, loud warning sign to any other developer who stumbles upon it.

Action 2: Comment Out the Code

Next, open the class file and comment out the entire body of the class. Leave the class definition, methods, and properties, but make them do nothing.

Action 3: Add a Clear Deprecation Notice

At the very top of the class file, add a large, impossible-to-miss block comment. This is your tombstone.

// =================================================================
// DEPRECATED as of 2025-10-30 by [Your Name]
//
// This class is believed to be unused and is scheduled for deletion
// after the quarantine period ends.
//
// It was replaced by the NewLeadProcessingService.
//
// If you see this message or believe this code is still in use,
// please contact the development team immediately.
// =================================================================

Action 4: Deploy and Run All Tests

Deploy this commented-out, renamed class to your sandbox and run all Apex tests. If a single test fails, congratulations! Your investigation in Step 1 missed something, and that failing test just acted as your safety net. It saved you from breaking production. You must now investigate that failure before proceeding.

Step 3: The Waiting Game - The Quarantine Period

Your "zombie" class is now deployed to production. It exists, but it does nothing. The most difficult part of the process begins now: waiting.

Let the code sit in this quarantined state for at least one full business cycle. For most features, this might be a month or a quarter. If you suspect the code was part of a year-end financial process, you must wait a full year.

This quarantine period is your ultimate safety net. It gives you time to see if any obscure, once-a-year process breaks. If something fails, the code hasn't been deleted. The logic is still there, just commented out. You can quickly restore it, analyze the dependency you missed, and live to fight another day.

Step 4: The Final Act - Deletion

The quarantine period has passed. The world did not end. No errors were reported. No one has screamed. Your confidence is now 100%. The time has come.

Action 1: Delete from Production

You can now safely delete the Apex class and its corresponding test class from your production org.

Action 2: Clean Up Your Version Control

Don't forget the final step! Remove the file from your Git repository. There's no point in cleaning up your org only to leave the file lingering in your source control forever.

Action 3: Celebrate Your Contribution to Code Health

Take a moment to appreciate what you've done. You didn't just delete code; you made the entire codebase cleaner, simpler, and easier to navigate for every other developer on your team. This is a huge win.

Conclusion: Subtraction is as Important as Addition

A healthy and mature codebase isn't just about adding new features. It's about having the discipline and courage to remove what is no longer needed.

Deleting code without a process is reckless. But deleting code with a safe, multi-step process is a sign of a professional and responsible engineering team.

Take a look at your own org today. Find one class you suspect is a digital ghost and take it through this process. Start cleaning up your codebase and make it a better place for everyone.