Many developers, especially those moved from native C/C++ to C#, have habits to put a “reserved” value in an enum definition that will probably contain additional values in the future. They think it can easily extend their code to fit the changes to this enum without code changes. For example, if a developer was working on a customer order system, he had to define an enum for the possible values for the customer types, because with the growth of his customer source, the types of the customer is subject to change in future. To fit any additional customer types in future but not to change the existing code, he might define this enum like this:
public enum CustomerType
{
SelfBusiness = 0,
Microsoft = 1,
HP = 2,
IBM = 3,
Intel = 4,
Reserved = 5
}
He put a reserved value at the end of the enum, indicating a possible value could be used in future. The reserved value is a placeholder of this enum.
In his code, he might use this enum like this:
public void ProcessCustomerOrder(CustomerType type, Guid orderId)
{
// Send the order to the different web services according to given customer type.
string webServiceUrl;
switch (type)
{
case CustomerType.HP:
webServiceUrl = http://mywebservice/sendorder?customerType=hp;
break;
case CustomerType.IBM:
webServiceUrl = http://mywebservice/sendorder?customerType=ibm;
break;
case CustomerType.Intel:
webServiceUrl = http://mywebservice/sendorder?customerType=intel;
break;
case CustomerType.Microsoft:
webServiceUrl = http://mywebservice/sendorder?customerType=msft;
break;
case CustomerType.Reserved: // Reserved.
default:
webServiceUrl = string.Empty;
break;
}
...
}
Noticed the reserved value is not currently used in this code, but once a new customer is introduced to his order system, he can then use the reserved placeholder to handle the possible value.
This design pattern is also common in the native world, let’s take one example, in Windows, some API take parameter which is a placeholder, see the CoInitialize function defined in ole32.h:
HRESULT CoInitialize(void* pReserved)
The pReserved argument is definitely not in use for this function, it is only for the future purpose if this function’s implementation is changed in future release of Windows.
Back to the topic, why should not define a reserved value in C#? Here are the reasons.
- Confusion: You should not expect the developers can understanding the value just because of its name. “Reserved” usually means it is a placeholder but however, if it is in a special case for example, to describe the status of a book reservation of a restaurant, the word “Reserved” means the reservation is successfully booked. Furthermore, it is hard to document this value.
- Unnecessary: The intension of adding a reserved value to an enum is just to fit the change to this enum in future, but the enums in .NET Framework build on a certain integral type, of which values can be easily extended in future. Developers should define the values that are currently being used for the enum, and define additional values in future if necessary. This may bring more readability to the code, easy to maintain, avoid any confusions of enum usages and documentation.
- Maintainability: To use a reserved value in an enum, developer may rename the reserved value to a more meaningful word in order to enhance the code readability, this is a heavy change to the existing code (the reserved values might be used many times prior it renames), which is also not expected.
In addition, to change an enum, you can:
- Add a value to the existing enum and keep using this enum.
- Add a new enum with new and original values and mark the old enum as obsoleted by using the System.ObsoleteAttribute attribute.
Do not try to suppress this message in most of cases; suppress this message only if the reserved values are being used in the current libraries which is previously shipped, or the word “Reserved” represents a different meaning rather than placeholder.
You can also visit this MSDN link for CA1700 to get more details.
Subscribe