When should I use the [Obsolete] attribute and when should I delete my code?

Question

The function of [Obsolete] is essentially to stop a class/function from being used but still to maintain it in code for the record.

Is there any good reason why [Obsolete] should be used as opposed to just deleting, or commenting out the code. This question is even more relevant if you have source control so there is no point keeping the code for reference purposes as it will be in the SC.

I'm curious as to what is considered best practice?

Marking code as obsolete would be more for consumers of your APIs. It gives them a chance to react and change to whatever the current method would be, before the obsolete code is actually removed. If it's just for your internal usage and not outside consumers, then there's no real reason to mark obsolete. — Glorin Oakenfoot, Nov 01 '16 at 13:27
more @http://stackoverflow.com/questions/3510892/usage-of-the-obsolete-attribute — Shekhar Pankaj, Nov 01 '16 at 13:29
@GlorinOakenfoot there is a reason. maybe you have more than one project with dependencies. E.g. your library A uses your library B. Maybe you don't want to change all code of A now, and just mark it, to modify it later. E.g. there is a method that is used in the other library on 200 places. You maybe want to fix it not all at once. (As long as the obsolete code is still correct). better solution would be to change the existing method, to call the new (not obsolete) code then. — Matthias Burger, Nov 01 '16 at 13:31

score 7 · Accepted Answer · answered Nov 01 '16 at 13:33

It is used mostly for backwards compatibility, so when you do a new implementation of a functionality that has a different expected behaviour, any code using the old functionality will still work, but you make sure that new uses of your library uses the new implementation.

If you are maintaining a library that is being used by third parties, you should develop a road map of when and if the obsolete functionality is going to be removed. The if it's important, because many times you are just indicating that that function is no longer to be maintained and the new one should be used instead.

Internally, it can be used in refactors to replace poorly-implemented-but-working functionality in a gradual way. You mark it as obsolete and start working through the warnings until you see no more of them, then you can proceed to safely remove it.

Be aware that this is an opinion based on experience on renewing legacy code bases and there is no common consensus.

You got a minor typo there "users" not "uses", Can't edit because minor edits aren't allowed. — fahadash, Nov 01 '16 at 13:40
@fahadash, I'm talking about new uses of the library. As in the action of using. — Yeray Cabello, Nov 01 '16 at 13:49

score 1 · Answer 2 · answered Nov 01 '16 at 13:32

The Obsolete attribute marks a program entity as one that is no longer recommended for use. Each use of an entity marked obsolete will subsequently generate a warning or an error, depending on how the attribute is configured.

Here an example for Hashtable comparer from reference source.

    [Obsolete("Please use KeyComparer properties.")]        
    protected IComparer comparer
    {
        get
        {
            if( _keycomparer is CompatibleComparer) {
                return ((CompatibleComparer)_keycomparer).Comparer;
            }    
            else if( _keycomparer == null) {
                return null;
            }                            
            else {
                throw new ArgumentException(Environment.GetResourceString("Arg_CannotMixComparisonInfrastructure"));
            }                
        }
        set
        {
            if (_keycomparer is CompatibleComparer) {
                CompatibleComparer keyComparer = (CompatibleComparer)_keycomparer;
                _keycomparer = new CompatibleComparer(value, keyComparer.HashCodeProvider);
            }
            else if( _keycomparer == null) {
                _keycomparer = new CompatibleComparer(value, (IHashCodeProvider)null);               
            }                
            else {
                throw new ArgumentException(Environment.GetResourceString("Arg_CannotMixComparisonInfrastructure"));
            }
        }
    }

program entity? and no it generates a compiler warning. not an error. — Matthias Burger, Nov 01 '16 at 13:33
If you define ObsoleteAttribute(String, true) an error will be thrown. — mybirthname, Nov 01 '16 at 13:35
@MatthiasBurger The attribute accepts a parameter which indicates whether usages result in a warning or error. Test it. (or just look at its documentation) — Servy, Nov 01 '16 at 13:37

score 0 · Answer 3 · answered Nov 01 '16 at 13:30

The documentation for the ObsoleteAttribute describes it's reasons for existence fairly well...

Marking an element as obsolete informs users that the element will be removed in future versions of the product.

As mentioned in the comments, this is obviously only really useful if others are using versions of your assembly.

When should I use the [Obsolete] attribute and when should I delete my code?

3 Answers3

Linked