Introduction

In Objective-C, deprecating a method means keeping it available for compatibility while asking the compiler to warn callers to move to a newer API. The important part is placing the deprecation annotation on the declaration that client code sees, usually in the header. A good deprecation also tells developers what to use instead.

Basic Attribute Syntax

The classic Objective-C way is to use the deprecated attribute.

- (void)oldMethod __attribute__((deprecated("Use -newMethod instead")));
- (void)newMethod;

When another source file calls oldMethod, the compiler emits a warning with your message.

This is the core mechanism and still useful when you need a direct, local annotation.

Put the Annotation in the Header

Deprecation warnings help callers only if the compiler sees the annotation at the public declaration site.

Example header:

1@interface MyService : NSObject
2
3- (void)oldMethod __attribute__((deprecated("Use -newMethod instead")));
4- (void)newMethod;
5
6@end

Implementation:

1@implementation MyService
2
3- (void)oldMethod {
4    [self newMethod];
5}
6
7- (void)newMethod {
8    NSLog(@"new implementation");
9}
10
11@end

The method can stay functional while callers are nudged toward the replacement.

Apple Macros Are Often Better

Apple SDKs provide convenience macros such as DEPRECATED_ATTRIBUTE, NS_DEPRECATED, and newer availability-style macros. These can be clearer and more expressive than raw attributes.

Simple example:

- (void)oldMethod DEPRECATED_ATTRIBUTE;

For more descriptive platform-aware declarations, availability macros are stronger:

- (void)oldMethod API_DEPRECATED("Use -newMethod instead", ios(10.0, 13.0));

This style is especially useful in frameworks and SDK-like code because it can communicate platform version history in addition to deprecation intent.

Deprecating Classes and Functions Too

The same concept applies beyond instance methods.

Class method:

+ (instancetype)legacyFactory __attribute__((deprecated("Use +factoryWithConfig: instead")));

C function:

void LegacyUtility(void) __attribute__((deprecated("Use NewUtility instead")));

The key pattern stays the same: annotate the declaration visible to callers.

Good Deprecation Design

A good deprecation message does two things:

1. states that the API is obsolete,
2. points to the replacement.

Bad:

- (void)oldMethod __attribute__((deprecated));

Better:

- (void)oldMethod __attribute__((deprecated("Use -newMethod instead")));

This turns a vague warning into a migration instruction.

Keep the Old Method Working During Transition

Deprecation is not removal. A common migration pattern is:

• mark old API deprecated,
• keep it functional,
• forward it internally if possible,
• remove it only in a later major cleanup.

That gives callers time to migrate without breaking builds immediately.

When to Use Availability Macros

If your code targets Apple platforms broadly and you care about version history, availability macros are often the best long-term choice because they align with how the Apple SDKs annotate APIs.

They are especially useful when:

• a method is deprecated only on some platforms,
• you want Xcode tooling to surface platform-specific warnings clearly,
• the API belongs to a reusable framework rather than to one app target.

Common Pitfalls

• Putting the deprecation annotation only in the implementation file where callers cannot benefit from it.
• Marking a method deprecated without naming the replacement API.
• Removing the old method immediately instead of giving consumers a migration window.
• Using raw attributes inconsistently across a larger codebase that already relies on Apple availability macros.
• Forgetting that class methods, functions, and other declarations may need the same treatment, not just instance methods.

Summary

• Mark Objective-C methods as deprecated with __attribute__((deprecated("..."))) or a platform macro.
• Put the annotation on the public declaration, usually in the header.
• Include a replacement method name in the warning message.
• Keep deprecated APIs working during a transition period when possible.
• Prefer Apple availability-style macros when platform versioning matters.