Adopting Objective‑C Nullability Annotations in a Mixed Swift/Obj‑C Codebase

Why Nullability Matters

When Swift consumes Objective‑C APIs, the compiler relies on nullability annotations to decide whether a pointer is an Optional or a non‑optional value. Without annotations, every Objective‑C pointer is imported as an implicitly unwrapped optional (AnyObject!), which hides potential nil‑related bugs and forces Swift callers to add defensive code. Adding nonnull and nullable annotations turns those silent failures into compile‑time warnings, improving safety and making the Swift interface clearer.

Desired Outcome

• All public Objective‑C headers expose a precise nullability contract.
• Swift call sites use the correct Optional annotations and receive compiler warnings when nil is passed to a nonnull parameter.
• Legacy runtime behaviour remains unchanged; annotations do not add runtime checks.

Prerequisites

1. Project uses Xcode 15 or later with an up‑to‑date Swift compiler.
2. Objective‑C source is split into header (.h) and implementation (.m) files.
3. Build settings allow adding compiler flags; you have access to the target’s Build Settings.
4. Team has a version‑controlled codebase so changes can be reviewed and reverted.

Step‑by‑Step Procedure

1. Enable Nullability Diagnostics

   In Xcode, open Build Settings for the target and add the following flags to Other C Flags (or Other Swift Flags if you prefer to see Swift warnings):

   -Wnullability-warnings
   -Wnullability-extension
   

   These flags make the compiler emit warnings when it encounters a nullability annotation that conflicts with the inferred type.

2. Wrap Headers with NS_ASSUME_NONNULL

   For each public header, add NS_ASSUME_NONNULL_BEGIN at the top and NS_ASSUME_NONNULL_END at the bottom. This tells the compiler that, by default, all pointer types are nonnull unless explicitly marked nullable.

   #import <Foundation/Foundation.h>
   
   NS_ASSUME_NONNULL_BEGIN
   
   @interface MyFormatter : NSObject
   @property (nonatomic, strong, null_resettable) NSDateFormatter *dateFormatter;
   - (NSString *)formatDate:(NSDate *)date;
   - (nullable NSString *)formatDateString:(NSString *)dateString;
   @end
   
   NS_ASSUME_NONNULL_END
   

   Notice the null_resettable property: it is non‑nullable for clients but can be set to nil to trigger a default value. Use this sparingly; for most properties nonnull is sufficient.

3. Annotate Ambiguous Pointers

   For pointers whose nullability cannot be inferred, use nullable or null_unspecified. The latter imports as an implicitly unwrapped optional and preserves the old behaviour if you cannot yet decide.

   - (nullable id)lookupObjectForKey:(NSString *)key;
   

4. Build and Verify Swift Import

   After editing a header, build the target. In Xcode’s Report Navigator look for warnings that mention nullability. A typical warning looks like:

   warning: 'dateFormatter' has no nullability attribute, defaulting to 'nonnull'

   Open the Generated Interface for the header (right‑click the header → Show Generated Interface) and confirm that the Swift types match your annotations. For example, dateFormatter should appear as NSDateFormatter (non‑optional) and formatDateString: as String?.

5. Test in Swift

   Create a small Swift file that imports the module and calls the annotated APIs:

   import MyModule
   let formatter = MyFormatter()
   let result = formatter.formatDateString("2026-10-13") // result: String?
   formatter.dateFormatter = nil // allowed because null_resettable
   

   Build the Swift target. If you passed nil to a nonnull parameter, the compiler will emit an error or warning depending on the -Werror setting.

6. Gradual Roll‑out

   Adopt annotations header‑by‑header. After each file, run a full build and run unit tests to confirm no behavioural changes. If a header change breaks many Swift call sites, you can:

   • Revert the header to its previous state.
   • Mark the problematic pointers as null_unspecified to restore the old implicitly unwrapped behaviour.
   • Document the change in the commit message for future review.
7. Treat Warnings as Errors in New Code

   In Build Settings, set Other C Flags to include -Werror=nonnull for new modules. This forces developers to fix nullability issues before merging. Existing legacy modules can remain with warnings until they are fully annotated.

8. Run Unit Tests

   Because annotations do not alter runtime behaviour, existing unit tests should pass unchanged. Run xcodebuild test for the target and verify that no new failures appear.

Expected Checks and Recovery

• Compile‑time check: No nonnull parameter receives nil in Swift code. The compiler will emit an error if -Werror=nonnull is enabled.
• Import check: The Swift generated interface shows Optional only where nullable is used.
• Runtime check: Run existing unit tests to confirm no crashes or behavioural changes.
• Rollback: If a header change introduces many Swift compilation errors, revert the header or mark ambiguous pointers as null_unspecified to preserve the old implicitly unwrapped optional behaviour.

Limitations

• Annotations are purely compile‑time; they do not add runtime nil checks. Existing nil crashes will still occur if callers rely on unexpected nil values.
• Blocks and function pointers require careful placement of the annotation. For example: void (^ _Nullable completion)(NSError * _Nullable).
• Different Xcode/Swift releases may interpret null_unspecified slightly differently; always test against the target toolchain.

Practical Verification Checklist

Step	What to Verify	Tool/Command
Build with annotations	No nullability warnings for annotated headers	Run xcodebuild -scheme YourScheme
Swift import	Optional types appear only where annotated	Open Generated Interface in Xcode
Swift call site	Compiler errors when passing nil to nonnull	Compile Swift file in Xcode
Unit tests	All tests pass, no crashes	Run xcodebuild test

Conclusion

Adding nullability annotations is a low‑risk, high‑benefit change. By wrapping headers with NS_ASSUME_NONNULL_BEGIN/END, annotating only the truly nullable pointers, and enabling strict diagnostics for new code, you make the Swift‑Objective‑C boundary explicit, reduce silent bugs, and provide clearer contracts to future developers.