Enum
From APIDesign
| Line 1: | Line 1: | ||
[[Java]] has been enhanced with [[wikipedia::Enumerated type|enums]] in version 1.5. The [[Enum]]s greatly simplify and standardize the way one can express the [[wikipedia::Enumerated Type|enumerated types]] in [[Java]]. However since their introduction I was not sure how suitable they are for [[API Design]] (I was not the only one, see few year's old [[Blogs:AndreiBadea:EnumsInAPIs|Andrei's post]]). Today I finished one [[Enum]] related [[API]] change for [[NetBeans]], and I felt all the pain. I guess I understand now what is wrong with [[Enum]]s in [[API]]s. | [[Java]] has been enhanced with [[wikipedia::Enumerated type|enums]] in version 1.5. The [[Enum]]s greatly simplify and standardize the way one can express the [[wikipedia::Enumerated Type|enumerated types]] in [[Java]]. However since their introduction I was not sure how suitable they are for [[API Design]] (I was not the only one, see few year's old [[Blogs:AndreiBadea:EnumsInAPIs|Andrei's post]]). Today I finished one [[Enum]] related [[API]] change for [[NetBeans]], and I felt all the pain. I guess I understand now what is wrong with [[Enum]]s in [[API]]s. | ||
| + | == Growing Set == | ||
| + | Designing [[API]] in proper way is about having prepared [[evolution]] plan in advance. One way of evolving an [[Enum]] is to enlarge the set of its constants. As [[Blogs:AndreiBadea:EnumsInAPIs|Andrei points out]] adding new [[enum]] constant is not strictly semantically [[BackwardCompatible]], but this [[evolution]] path has been well thought in advance when [[Enum]]s were designed. | ||
| + | Each switch statement (over an [[Enum]]) needs to have ''default'' branch. In case new constants are added, the code ends up in there. The behaviour may slightly change with newer versions, the ''default'' branch may be used more and more often, but overall, there are no surprises. Neither on [[API]] publisher, neither on [[API]] consumer side. | ||
| + | |||
| + | == Infinite Set == | ||
[[TBD]]: Story about AU.CATEGORY | [[TBD]]: Story about AU.CATEGORY | ||
Revision as of 18:08, 9 January 2011
Java has been enhanced with enums in version 1.5. The Enums greatly simplify and standardize the way one can express the enumerated types in Java. However since their introduction I was not sure how suitable they are for API Design (I was not the only one, see few year's old Andrei's post). Today I finished one Enum related API change for NetBeans, and I felt all the pain. I guess I understand now what is wrong with Enums in APIs.
Growing Set
Designing API in proper way is about having prepared evolution plan in advance. One way of evolving an Enum is to enlarge the set of its constants. As Andrei points out adding new enum constant is not strictly semantically BackwardCompatible, but this evolution path has been well thought in advance when Enums were designed.
Each switch statement (over an Enum) needs to have default branch. In case new constants are added, the code ends up in there. The behaviour may slightly change with newer versions, the default branch may be used more and more often, but overall, there are no surprises. Neither on API publisher, neither on API consumer side.
Infinite Set
TBD: Story about AU.CATEGORY
Follow
