[Insight-developers] API Changes in itkSpatialObject

[Zachary Pincus]

Bill -

Sorry about not providing more documentation/email/lead-time before  
the method signature change.

I'm glad the new policy appears to allow for changing method  
signatures when the original versions were clearly in error, and  
could themselves lead to cryptic compiler errors. Nevertheles your  
point about changing user-facing code is well-taken.

What steps should I take to properly document this (and any future  
similar changes made with the blessing of the developer list)? I'll  
add explicit documentation to the header, and send an email to the  
users list -- anything else that should be done?

Zach


On Jan 17, 2006, at 5:02 AM, Lorensen, William E (GE, Research) wrote:

> Folks,
>
> I've been working on a draft policy for API Backward Compatibility  
> for Insight Consortium software. It's just its draft form now.
>
> The basic principle of this policy is that once an API appears in  
> an official release, it cannot be removed.
>
> API's can change if:
> 1. The compiler, if possible, can warn the user about the  
> deprecated API. Some compilers show line numbers where the  
> deprecated API is being used.
> 2. At run-time, deprecated API's report how to change code from the  
> old API to the new API.
> 3. Documentation in the deprecated code clearly informs the user  
> how to move the code from the old API to the new API.
>
> Section 3.6 of the draft covers Method Signature Changes:
> Once appearing in an official release, changes to a public or  
> protected method 's signature are not permitted. Changes can be  
> made to private methods since these are not accessible outside the  
> class.
>
> The rationale is: Changes to a method's signature will cause  
> compilation errors in user code that accesses the method. The  
> compiler error cannot specifically contain corrective action.
>
> The workaround is: A new method should be added with the new  
> signature. If only the method's parameters are changing, then both  
> the old and new methods may be able to co-exist. If the return type  
> of the new method is different from the return type of the old  
> signature, then a new method name should be created. If the ISC  
> supported compilers cannot compile the method with both signatures,  
> then new signature must use a new method name.
>
> --------------------
> Unfortunately, the method changed in SpatialObject is a public  
> method that cannot co-exist with the old API so there is not a  
> mechanism other than code documentation, e-mail, etc. to notify the  
> user. A new method name could solve the issue, but it is not clear  
> what that name should be.
>
> The current PDF of the draft is at:
> http://insightsoftwareconsortium.org/wiki/index.php/Administration- 
> BackwardCompatibility
>
> This draft has not been reviewed by other ISC members and has not  
> yet been adopted by the ISC.
>
> Bill
>
> _______________________________________________
> Insight-developers mailing list
> Insight-developers at itk.org
> http://www.itk.org/mailman/listinfo/insight-developers