Designing System.TimeZone2 - Part 1 (API naming and new class or not)

Didn't I say it two weeks ago that API naming is the most difficult thing? :) My BCL post on System.TimeZone2 has been out for about 12 hours, and the top complaint has been .... can you guess it... yes... the name!

You might even think that I knew this was going to attract some controversy and so I prep you guys with that post. But no, naming the new class System.TimeZone2 was not a controversal witin Microsoft at all. It doesn't even make it into the top 10 debated names. ;) Once we have reached the decision that we do need a new class for the extended time zone functionality and that this new class was going to totally replace System.TimeZone. There was no question in any of our reviewers' or approvers' mind what this class should be called. Actually, we all agree that calling it by any other name will actually make it more ambiguous what our intentions is.

Users of the .NET framework will know, System.TimeZone2 is to replace System.TimeZone. There is no functionatlity that can be performed in System.TimeZone that cannot be done with System.TimeZone2. We did see people cringe at first, but that's more of a gut reaction to.. why can't we extend System.TimeZone rather than the naming issue. Now why is extending Time Zone support a whole different class is much worthier debate in my mind.

I know some people have been wondering whether this decision was made because of this Orcas "Red" bits vs Orcas "Green" bits limitation. No need to call the MythBusters... I can bust this myth right here and now. This is not the reason. Every feature in Orcas goes through an Architect review to make sure we don't add a new class just because of this "Red" bits "Green" bits rule. (Trust me.. we don't like adding new classes, and we are VERY concern about framework pollution.) If extending System.TimeZone was what we're going to do anyways, then we'll do it in "Red" bits or wait a release. However, after weighing in the pros and cons, it was obvious to us that we'll never just modify System.TimeZone.

It is obvious in the beginning that if we were to extend time zone support in the framework, we have to support Vista's Dynamic Time Zone APIs. Otherwise, we are just bandaiding the problem and waiting for another TimeZone++ to happen. Leveraging Vista's dynamic time zone support is equivalent to overhauling and dumping the old time zone functionality. The whole idea of "daylightsaving" time is different. We're now looking at historic data as well as current data.

Next, we took a look of most requested features from our customers (yes... we do listen.. send us more feedback!) and took a look at what System.TimeZone already has. It was decided that if we were to add a new class, there is no reason to add support to Vista's dynamic time zone and these new features without also having all System.TimeZone's functionality (but implemented differently). (Side Note: We did thought about having a class that doesn't replace System.TimeZone, but merely augments it for the extra support. But it wasn't hard to realize that wouldn't be good.) So, how much breaking changes would require System.TimeZone to have if we were to add all these new features? The answer is .... a lot. I asked last time.. how much breaking will our users tolerate? So, after weighing in everything, we decided that we need a new class, and this new class that needs to do everything that System.TimeZone does. So it only make sense to deprecate System.TimeZone, and introduce this new class as its replacement.

Now, regarding everyone's feeling about the guideline:

"Do use a numeric suffix to indicate a new version of an existing API if the existing name of the API is the only name that makes sense"

I actually pinged Brad and Krzsyztof about your feedback. Hopefully one of them will post something about this soon. :)

I hope this explains some of our reasoning. What do you think? Agree? Disagree?

Comments

• Anonymous
  October 03, 2006
  I really do not like the using numbers in the class names.If you need to create a new class I suppose you are adding breaking functionality. This functionality should have a reason or a meaning, aking to a name. Class2, Class3 does not indicate the difference what you need.Just an example. You say that "we have to support Vista's Dynamic Time Zone APIs." -> Why not System.DynamicTimeZone. It clears doubt why use one or another. LT

• Anonymous
  October 03, 2006
  As long as Microsoft stays consistent, I do not mind the numbering guideline.

• Anonymous
  October 03, 2006
  I have to say I hate the idea of TimeZone2.My way of going about this would be to mark everything in the current TimeZone as Obsolete and add the new functionality to it. Then in vNext, it would simply disappear. You could even decide that you don't want to mark it as obsolete and simply replace the type completely.The whole point of this is that since you can run .NET versions SxS, no one would really get hurt from this.If you're thinking about how confusing it would be for someone to see all of the new and old ways of working with TimeZone together through IntelliSense, then I'm sorry to say this, but you might as well reconsider the Obsolete attribute (which is a good idea IMHO).

• Anonymous
  October 03, 2006
  I would prefer breaking changes in this case...In short term this may be painful, but in the longterm it's a better choice.I also would like to thank you for listening to our feedback and responding to it. Your team has done a great job so far!Thanks,Thomas Krause

• Anonymous
  October 04, 2006
  Hi Laura, We have considered calling it "TimeZoneDynamic". (Calling it with a prefix breaks the intellisense link and reduce discoverability... it's also in the guidelines.) However, when running in Window XP without Dynamic Time Zone support, this feature does not have dynamic time zone support. So, calling it TimeZoneDynamic would also be misleading. Thanks, Kathy

• Anonymous
  October 04, 2006
  You could just indicate that its an extended TimeZone:TimeZoneExtendedYou could make it more descriptive:TimeZoneDataTimeZoneInformationOr perhaps indicate what's new:TimeZoneDynamicSupportTimeZoneVistaCompatibleOr just tell it as it is:TimeZoneUseThisOneTheOldOneIsStupidAnd what are the top 10 most debated names?

• Anonymous
  October 04, 2006
  Let's go through all the names you've suggested: TimeZoneExtended: If we were to call it "TimeZoneExtended", why dont we just call it "TimeZoneEx"?
  Again.. Page 47 of the .NET Design Guidelines:
  "DO NOT use the "Ex" (or similar) suffix for an identifier to distinguish it from an earlier version of the same API." Also, I know I am quoting the guidelines a lot. I am not saying because the guideline say so... therefore we're doing it this way. But these are the guidelines te BCL team came up, and as the BCL team, we strongly believe the guidelines will help us create a more consistent framework. TimeZoneData: The .NET Framework actually doesn't store any time zone data. We use the OS's data. So calling the class as such is misleading. TimeZoneInformation: Too long. :( This is a core type. TimeZoneDynamicSupport: Doesn't have built in Dynamic Time Zone support if your OS doesn't have it, because we rely on the OS to give us the Dynamic Time Zone data. If you create a TimeZone2 object, it can have Dynamic Time Zone support though. This may be confusing the normal user who expects it to have Dynamic Time Zone support at all times. Also, this is too long. TimeZoneVistaCompatible: It is not just Vista compatible. It is compatible with Vista and beyond. Plus, it works on XP as well. This will be misleading to users, plus it is too long. TimeZoneUseThisOneTheOldOneIsStupid: Hey, that's what TimeZone2 is suppose to communicate, but in a much shorter way. :) Remember, I discuss the principles of naming an API here. For the BCL team, short is VERY important. When Anders review our API naming, length of name is one of the things he is concern about.

• Anonymous
  October 05, 2006
  The comment has been removed

• Anonymous
  October 05, 2006
  Hey,You said in your previous comments (in the BCL post):"After much consideration, we've determined that updating TimeZone would cause too much breaking changes because of the Vista Dynamic Time Zone support. APIs like "GetUtcOffset" and "IsDaylightSavingTime" works on a totally different logic. "However since Windows XP won't support the new Dynamic Time Zone features either way, I am confused. Theoretically this would mean that you are worried about a breaking change between two Framework versions, but don't have a problem introducing the same "breaking change" between two operating systems running the same framework version???Thomas Krause

• Anonymous
  October 05, 2006
  Hey Thomas, I blogged my response in Designing TimeZone2 - Part 2. Let me know what you think. I hope that explains why the different results across OS are not breaking changes, where as augmenting System.TimeZone is. Thanks, Kathy

• Anonymous
  October 06, 2006
  The comment has been removed

• Anonymous
  October 06, 2006
  Hi Ciarang, I covered this in Part 2. :) Let me know if you still have any questions. Thanks, Kathy

• Anonymous
  October 10, 2006
  Ever since Kathy Kam announced on her weblog that a new type named TimeZone2 will be introduced into

• Anonymous
  July 29, 2007
  Let's forget TimeZone2. It has been renamed to TimeZoneInfo.