Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have the need to phase out an obsolete method. I am aware of the [Obsolete] attribute. Does Microsoft have a recommended best practice guide for doing this?

Here's my current plan:

A. I do not want to create a new assembly because developers would have to add a new reference to their projects and I expect to get a lot of grief from my boss and co-workers if they must do this. We also do not maintain multiple assembly versions. We only use the latest version. Changing this practice would require changing our deployment process which is a big issue (have to teach people how to do things with TFS instead of FinalBuilder and get them to give up FinalBuilder)

B. Mark the old method obsolete.

C. Because the implementation is changing (not the method signature), I need to rename the method rather than create an overload. So, to make users aware of the proper method I plan to add a message to the [Obsolete] attribute. This part bothers me, because the only change I'm making is decoupling the method from the connection string. But, because I'm not adding a new assembly, I see no way around this.

Result:

[Obsolete("Please don't use this anymore because it does not implement IMyDbProvider.  Use XXX instead.")];
        /// <summary>
        /// 
        /// </summary>
        /// <param name="settingName"></param>
        /// <returns></returns>
        public static Dictionary<string, Setting> ReadSettings(string settingName)
        {
            return ReadSettings(settingName, SomeGeneralClass.ConnectionString);
        }

        public Dictionary<string, Setting> ReadSettings2(string settingName)
        {
            return ReadSettings(settingName);// IMyDbProvider.ConnectionString private member added to class.  Probably have to make this an instance method.
        }
share|improve this question
add comment

2 Answers

up vote 5 down vote accepted

Microsoft uses the [obsolete] attribute to tell developers that the method, property or class is deprecated, and may be changed (or not supported at all) in future releases.

That gives you at least one release cycle to notify users of your API that their feature is "going away," and to remove references to it in future releases of their software.

How long you leave the original feature in is entirely up to you. If you want to "strongly encourage" developers to use your new features over the old ones, you only need one additional release cycle to remove it. If you intend to have permanent backwards compatibility, you can leave it in forever.

As Brian points out, if you're only changing the underlying implementation, but not the method signature, you may not need to do any of this at all.

share|improve this answer
    
Microsoft's practice is generally to remove a deprecated thing in the next major release. By contrast, Java never removes deprecated things - so it's up to you. –  Scott Wilson Apr 9 '12 at 16:13
    
We do not version assemblies beyond the application level (1 giant application with many solutions). Combine this with the fact that the # of solutions that depend on any given assembly are undefined. I can't test an application that I don't know about. But, if I make a change that causes a breakage of an application that I don't know about...well that's my fault. This is why I renamed the method. So, from what I have read thus far there is no better way to go about this. –  P.Brian.Mackey Apr 9 '12 at 18:41
add comment

Because the implementation is changing (not the method signature), I need to rename the method rather than create an overload.

I don't understand. If the implementation is changing but the signature isn't, why would you ever do this? Let the "old" method use the new and improved implementation. Any developers consuming this API will be rolling their eyes when they see a method with the exact same signature created and deprecation warnings on their existing method calls. (Can you think of a time this has ever happened in an API?)

If you're unsure if changing the underlying implementation of this method will work, verify behavior with unit tests before and after you change the implementation.

share|improve this answer
    
That's a nice ideal. The issue is that we have no testing harnesses in place. That is another issue alltogether that I hope to get resolved. So because there is no integration testing, I cannot do what you recommend. There are too many yet undefined depencies in place that will go untested. –  P.Brian.Mackey Apr 9 '12 at 18:01
    
The reason I mentioned testing is because you clearly wanted to do this so those consuming your API would do the testing and help you figure out any issues between the 2 calls. Your best option seems to be to throw the developers using your code into the fire and make them use the new implementation and hope they do thorough QA or have tests of their own. –  brian Apr 9 '12 at 18:22
    
I'd be throwing myself into the fire. I'd rather stick with the original code that I posted. That way nobody calls me at 3am wondering why the production code broke. Then, depend on the developers to solve the code obsolescence as they go through and repair their warning flags. If they don't fix it at that point, then when the connection strings start failing on them its their fault for not repairing their warning flags...not mine. –  P.Brian.Mackey Apr 9 '12 at 18:25
    
Whenever you write new code you run the risk of introducing problems. Tests will let you refactor without being so afraid. Fear is the mind-killer. Plus you're just delaying the inevitable; they will begrudgingly add a "2" to their call a couple of iterations from now and you'll be getting the same phone call if it doesn't work. –  brian Apr 9 '12 at 18:32
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.