At work yesterday, I learned a cool method for letting other engineers know about the deprecated state of a particular method. We use privately created and supported Cocoapods to offer software modules, maintained by us, for use by the various and sundry corporate properties. Access to the Cocoapods private repository is good enough to earn access to our software modules (pods).
However, from time to time and sometimes without much warning the method signature need to be changed. So, we’ve developed a pretty common, but assuredly best-practice, to warn new pod consumers that this service is ‘deprecated’ and to recommend they use that one. This warning is great for new users, but what do we do for existing pod consumers who have no warning.
Sudden loss of a method’s presence would inadvertently create a nasty scenario where the engineer has to do a minor adjustment, downloads the repo and then does pod install only to discover that the project won’t build because of this service no longer being there…. argh… This won’t necessary affect any end user, but will certainly affect the engineer trying to get a minor update out to that end user.
The best practice is this:
- Create the new method. Document it.
- In the .h (for objective C) public reference to the method, add this to the end of the signature
- __attribute__((deprecated(“Use _THIS_HANDY_DANDY_NEW_METHOD_NAME instead”)));
- Next, hollow out the old method so it consumes the new method with the extra parameters appropriately defaulted or assumed.
The net effect is that any consumer of the old method gets to see a deprecation warning in Xcode with a suggestion on what to use instead. The auto-code-completion feature of Xcode shows the deprecated service with a red line through it! Existing users of the pod are none-the-wiser. Backwards compatibility maintained. Ahhh. Nice.
