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

  • Article

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?