Usage of the Obsolete attribute

Question

I was recently told it was bad practice to haved marked a number of methods in our code with the [Obsolete] attribute.

[Obsolete("This property is obsolete. Use NewProperty instead.", false)]
public string OldProperty { get; set; }

[Obsolete("This method is obsolete. Use NewMethod instead.", false)]
public void OldMethod()
{
    // Method implementation
}

These methods were internal to our codebase, rather than being on an API. The methods handled an older encryption function.

I felt it was a quick and safe way to denote to the rest of the team that these methods should not be used, and provided a message to suggest alternatives.

Others felt that I should have removed the methods entirely, rewriting or refactoring existing code as required. Additionally, it was thought too easy to overlook the compiler warnings.

Rather than relying on opinions, is there an official or recommended 'best practice' for marking code as Obsolete (at least when it's not being used by 3rd parties)? Or if not, is this a largely subjective matter?

Answer 1

Step 1. Mark the member or class as [Obsolete]

Step 2. Update all internal uses of the member or class to either use the new approach that replaces the obsolete approach, or mark that member or class itself as [Obsolete]

Step 3. If you've marked new stuff as [Obsolete] in Step 2, repeat this step as needed.

Step 4. Remove all obsolete members and classes that are neither public nor used by an obsolete public member or class.

Step 5. Update documentation to give a clearer description of the approach recommended to replace any public obsolete members or classes.

At the end of this, you will have no obsolete code that is solely used by internal code. There's nothing to say that you have to do all of this in one go though; at each stage you have made progress. The time between starting step 1 and ending step 5 could be 5 seconds or 5 years, depending on many factors (most of them to do with complexity).

Incidentally, if someone finds it easy to ignore compiler warnings, the problem is not with [Obsolete]. However, one reason not to leave such calls in the code for long (that is, to have done as far as step 2 ASAP) is to make sure people don't end up becoming used to compiler warnings as they're part of the habitual response to compiling the code.