Naming convention: how to name another version of the same class?

Question

I have a class MyClass that has an implementation error. The class is part of the library, so I can’t change the implementation of the class, because it will silently change the behavior for existing clients (clients who in this case can rely on the error: see for example ( https://connect.microsoft.com/VisualStudio / feedback / details / 790160 / httpclient-throws-operationcanceledexception-insead-of-timeoutexception ))

I need to create a second version of the same class that includes error correction. I have seen such situations before, but the name I saw was always incremental Eg MyClass2 , MyClass3 .

These cases are probably quite rare, however, I was wondering if there is a better way to name these "versioned" classes. I imagine a solution that grows over time and has several classes of this type that can probably be really confusing, especially for a library. I suggest that I need to choose between MyClass , MyClassV2 , MyClassV3 , etc.

Answer 1

I was wondering if there is a better way to name these "versioned" classes.

There is no .NET naming convention for "classes that fix errors in other classes." I would advise other developers at your workplace and see if they have any company agreements for such a thing. I think consistency is more important than the actual name.

And on the side notes for your problem, I would not create a new class at all. I would DeprecatedAttribute method and implement the logic inside the same class by providing a new set of API methods that are properly documented to state that they are here as a fix. Your library’s clients are probably already familiar with MyClass , and this will make them easier to use, alternating with the need to ask myself, each time, “which version of this should I use.”

Answer 2

In an ideal world, new versions will introduce additional features while maintaining 100% backward compatibility with previous versions of the API. Unfortunately, an ideal world remains elusive, and it is not always possible to maintain full backward compatibility. The suffix with the version is a suitable pattern in this case.

The standard .NET naming convention is to use incremental numbering like Class , Class2 , Class3 , etc. This comes from a naming convention for COM interfaces designed specifically for your use of the description. For example, the IHTMLDocument interface currently has 8 versions, from IHTMLDocument to IHTMLDocument8 .

In the original Wireframe Design Guide, the book by Qualina and Abrams explicitly recommended this practice when the authors said the following:

DO use a numeric suffix to indicate a new version of an existing API if the existing API name is the only name that makes sense (i.e., it is an industry standard) and adding any meaningful suffix (or changing the name) is not a suitable option.

 // old API [Obsolete("This type is obsolete. Please use the new version of the same class, X509Certificate2."] public class X509Certificate { ... } // new API public class X509Certificate2 { ... } 

The old convention, followed by the original Windows team, was to add the Ex suffix to new and improved versions of the API, which comes from the word "extend." However, it does not scale very well, which leads to confusing ExEx functions. I do not think that was ExExEx ; everyone was afraid to touch these APIs. Framework design guides explicitly recommend against this practice, people who went to the .NET architecture after learning their lesson:

DO NOT use the “Ex” suffix (or similar) for an identifier to distinguish it from an earlier version of the same API.

 [Obsolete("This type is obsolete. ..."] public class Car { ... } // new API public class CarEx { ... } // the wrong way public class CarNew { ... } // the wrong way public class Car2 { ... } // the right way public class Automobile { ... } // the right way 

Obviously, since their latest code example tells you if you add support for a particular function in the new version of the API, you would be better off not calling the new class / interface a reference to that particular function.

Although the above focuses almost exclusively on classes and interfaces, the same logic will be true for any member functions of this class that may be added in future versions. The original function can retain its original name, and the newly added function has a different name that either reflects its iteration or its added functionality.

Answer 3

I would copy all the behavior of your existing class to a new one, rename the original one, indicating that the class is deprecated, rename the new one to the actual name from earlier and mark the original (with the new name now) as [Obsolete] , indicating that it should no longer be used. Thus, the entire consumption code automatically triggers a new behavior. Thus, your new class with the correct behavior gets the name of the source class, where the buggies get the version number, for example.

For legacy code, you can do the opposite, create a new class with a new name and mark the old one as Obsolete . I know the SDK with the version number, where the last number indicates the latest version of the class, and everyone else has this attribute along with the notification in the documents, which mentions that the class has been replaced with the new version.

Answer 4

I think the name of the duplication class will seriously confuse other people overtime. You retrieve a method with a C # interface and implement a different version.

Answer 5

For clarity, if this happens, I use ClassV2. This indicates that this is a different version of the class.