.NET Best Practices – Phasing Out Obsolete Code

net

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.
        }

Best Answer

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.

Related Topic