{"id":110873,"date":"2025-02-17T07:00:00","date_gmt":"2025-02-17T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=110873"},"modified":"2025-02-15T08:03:19","modified_gmt":"2025-02-15T16:03:19","slug":"20250217-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20250217-00\/?p=110873","title":{"rendered":"API design note: Beware of adding an “Other” enum value"},"content":{"rendered":"

Consider the following API:<\/p>\n

enum class WidgetFlavor\r\n{\r\n    Vanilla,\r\n    Chocolate,\r\n    Strawberry,\r\n    Other,<\/span>\r\n};\r\n\r\nWidgetFlavor GetWidgetFlavor(HWIDGET widget);\r\n<\/pre>\n
The idea here is that Widgets come in three flavors today, but we might add new flavors in the future, so we add an Other<\/code> value to cover any future flavors.<\/p>\n
This is a problem.<\/p>\n
Suppose we do indeed add a new flavor Mint<\/code> in the next version.<\/p>\n
enum class WidgetFlavor\r\n{\r\n    Vanilla,\r\n    Chocolate,\r\n    Strawberry,\r\n    Other,\r\n    Mint,<\/span>\r\n};\r\n<\/pre>\n
What flavor should you report if somebody calls Get\u00adWidget\u00adFlavor<\/code> and the widget is mint?<\/p>\n
If you return WidgetFlavor::Mint<\/code>, then this will confuse code written with the Version\u00a01 API, because they expected to get Other<\/code> for anything that isn’t vanilla, chocolate, or strawberry. The word “other” means “not mentioned elsewhere”, so the presence of an Other<\/code> logically implies that the enumeration is exhaustive.<\/p>\n
On the other hand, you obviously should return WidgetFlavor::Mint<\/code> because that’s why you added the value to the enum in the first place!<\/p>\n
My recommendation is not to have an Other<\/code> at all. Just document that the enumeration is open-ended, and programs should treat any unrecognized values as if they were “Other”. Any code that uses this enumeration will therefore put all unrecognized values into an app-defined “Other” category on their own. Now you can add Mint<\/code>: New code will put minty widgets in a “Mint” category, and old code will continue to put them in the app=defined “Other” category.<\/p>\n","protected":false},"excerpt":{"rendered":"
What are you going to do when you add a new kind?<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-110873","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
What are you going to do when you add a new kind?<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110873","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=110873"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110873\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=110873"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=110873"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=110873"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}