Kathy Kam : API Design

Orcas October CTP available - Hello, "System.DateTimeOffset"!

KathyKam — Tue, 31 Oct 2006 00:56:00 GMT

Once again, I am very excited that the new CTP is available. :) My second feature for Orcas is available to the world! The BCL team has gotten plenty of feedback (as you can see the comments from my BCL post and on this blog...) about needing an object to represent exact point in time! (We do listen!!)

Oh and for those of you who has been reading my blog regularly... this is the third most debated name on the BCL: "DateTimeOffset". I will explain why later this month in my "Desiging DateTimeOffset" posts. Again, a starter guide will be posted on the BCL blog very soon. This time, I think our new PM Justin will be doing it instead of me. I still need to write a "Advance feature for TimeZone2".

A new date time data structure that can specify an exact point in time relative to the UTC time zone.

The current DateTime is insufficient at specifying an exact point in time. DateTimeOffset represents a date time with an offset. It is not meant to be a replacement for DateTime; it should be used in scenarios involving absolute points in time. DateTimeOffset includes most of the functionality of the current DateTime API and allows seamless conversion to DateTime as well.

Again, for my loyal readers here... a little sneak preview

void CreatingADateTimeOffset()

{

DateTime currentDateTime = GetUserDateTime();

TimeSpan userOffset = GetUserOffset();

DateTimeOffset pointInTime = new DateTimeOffset(currentDateTime , userOffset);

}

API Naming - Most debated name on the BCL are...

KathyKam — Mon, 09 Oct 2006 18:00:00 GMT

So.. in my previous post, I asked "which two names wa the most debated names on the BCL". Well, the types that got the most debate for its name are:

Nullable<T>
Collection<T>

Surprised? Not suprised? Do you think they are named appropriately?

<Editorial Coment>
Why is there only 2? Shouldn't you tell me "Top 3"?
"Hardest API to name #3" should be available in the next Orcas CTP. So I won't let the cat out of the bag just yet. :)
</Editorial Coment>

Naming Guideline Discussion

KathyKam — Sat, 07 Oct 2006 03:53:00 GMT

Yeah.. Krzysztof have finally blogged about the controversial naming guidelines around TimeZone2!

Check it out: http://blogs.msdn.com/kcwalina/archive/2006/10/06/TimeZone2Naming.aspx

Also, I'd like to repost one of my responses to the names 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.

Designing System.TimeZone2 - Part 2 (Dynamic Time Zone support)

KathyKam — Fri, 06 Oct 2006 03:59:00 GMT

There are some great discussion on the differences between System.TimeZone and System.TimeZone2 and what exactly is Vista Dynamic Time Zone in my previous post. So I thought I'll spend Part 2 talking about it.

So what exactly is the difference? I have mentioned again and again that the difference is in "Vista Dynamic Time Zone support". But another major difference is that, in System.TimeZone the only time zone you can use was current time zone. That's it. TimeZone2 is way more flexible than that. Users can create their own time zone using the CreateTimeZone API or use the OS provided time zone. (I really need to blog about the CreateTimeZone API... that's on my to-do list)

"So what exactly is this "Vista Dynamic Time Zone support"?"

The word "dynamic" itself is a little misleading. It is not "dynamic". It is more "historic" or "futuristic". "Dynamic time zone data" is just the new registry structure that Vista has introduced so that an application can query a time zone's historic (and future) data. It is dynamic in the sense that as you move forward it time, the OS will update your current time zone information based on the data.

"So does TimeZone2 do different things on different OS?"

Short Answer: No it does not.

Long Explaination:

Let's take a look at "IsDaylightSavingTime".

For System.TimeZone2:
public bool IsDaylightSavingTime (
DateTime time
)

On Vista, if you call FindSystemTimeZoneById, TimeZone2 will be populated with historic and future time zone data (aka dynamic time zone data). On Win XP, if the OS has not been updated with this new data (we are hoping that Windows will backport dynamic time zone data to XP btw...), TimeZone2 will be populated with the current time zone data the OS provides. TimeZone2 doesn't have different logic. The difference here is the data that was provided by the OS. The difference is in FindSystemTimeZoneById(). The call "IsDaylightSavingTime()" does the same thing in both OS.

Two TimeZone2 object with the same data will return the same thing across all the instance methods. You can populate a TimeZone2 object with historical data in WinXP and it will work like it does in Vista. Similarly you can also populate a TimeZone2 object without historical data in Vista and it will work like it does in XP. It all works the same.

The only difference the different OS brings is in the static methods that queries data from the OS. If the OS have different data, the static methods will return different results. This is no different to if you call "GetOSHelloString()" and one OS returns strHello = "Hello World", and another reutrns strHello = "Hello". Would you consider strHello.Length returnng different results and "doing different things on different OS"?

The APIs that calls the OS to get the data all have the word "SystemTimeZone" in it.

- GetSystemTimeZone()
- FindSystemTimeZoneById(string id)
- ConvertBySystemTimeZoneId(string id)

So the "SystemTimeZone" APIs are really helpers for you to get to the OS time zone data. TimeZone2 can operate on other data. (Again, I really need to post a blog about the CreateTimeZone APIs... )

For developers who wants to use OS data but is worried about different OS having different data, we do recomend them serializing the TimeZone data when doing cross application communication.

Now let's look at System.TimeZone, for the same API. It behaves completely differently.
public static bool IsDaylightSavingTime (
DateTime time,
DaylightTime daylightTimes
)

First of all, it is a static method. Secondly, it takes a DaylightTime to calculate whether it is in daylight saving time. It has no understanding of the OS time zone data.

This is why just augmenting or changing System.TimeZone will be a huge breaking change for our exisiting customers. Basically, we'll gut System.TimeZone and replace it with what we call "System.TimeZone2". When we realize that's what we'll do. We decided that we are basically creating a new type. Thus, the birth of System.TimeZone2.

Does this make sense? Do you agree? Disagree?

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

KathyKam — Wed, 04 Oct 2006 07:20:00 GMT

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?

API Naming - API Design

KathyKam — Tue, 26 Sep 2006 03:08:00 GMT

Before becoming a PM, I attended one of those annual Program Manager conference in Microsoft. I attended a talk that particularly stuck in my mind today as I discuss API naming. It was called "Six Skills of Feature Design Leaders ". The speaker is a UI PM, so naturally, his examples were focused on designing UI components. To emphsis one of his points, he discussed about the difficulity a PM would experience because everyone thinks they are an expert and thus have a say in it. He asks us how often do we go tell a Dev or a Tester that they are doing their job wrong, vesus how often a Dev or a Tester telling you that the UI is wrong (e.g. the button is the wrong color). Therefore he concluded that feature design is a skill that needs to be master and one of the things you need to master is to design something even though it is easy for everyone to have an opinion. (ie. "Everyone's a UI designer!")

I didn't not think about this much after I became a PM. I was moving to Deveoper Division. Surely, that didn't apply to me. Designing APIs is very different from desigining UI. Yes, everyone can have a say in the UI, but code? I was wrong.

API naming was surprisingly like designing UI. Everyone does have an opinion and everyone is an expert. If we were to make a new type in Orcas that has 3 elements. A Date, a time and an UTC offset. What should that be called?

- DateTimeUtcOffset
- TimeDateUtcOffset
- PointInTime
- DateTimeWithOffset
- DateTimeOffset
- DateTimeStandard
- DateTimeRelative
- DateTimeAbsolute

Just off the top of my head, I can name about 20 different names that are acceptable. Some I prefer over others, but different people prefer different things. How do you decide what name to go wth? What are the principals?

Here is what I learnt from my time on the BCL team:

1) Names should be as short as possible.

We are making a base type here. Though VS intellisense makes typing long names easy, that doesn't mean EVERYONE will use VS.

2) Name should descibe the type

The name should describe the name as best as possble, and also make it similar to related types. For example, what if we name "DirectoryInfo" as the class that describe a directory, and "FileDescription" as the class that describe a file? People who are familiar with one type will not easily associate the two types. That is why, we named them "DirectoryInfo" and "FileInfo".

3) Name should follow .NET Design Guidelines

The BCL team came out with the guidelines for consistency. Thus it is vital that names follow the guidelines

4) Name should not be "close enough"

Don't call your type something when it is not. I have had people who suggest names that are "close enough, people don't know the difference anyways". That's underestimating our users, plus this is just bad news all the way. If I have a type that contains a date, a time and a UTC Offset. Naming it "DateTimeTimeZone" is just wrong. It doesn't contain a System.TimeZone object! An UTC Offset can map to several Time Zones and represent none. People will make the wrong assumptions because you named it carelessly.

So, can you guess which two names was the most debated names on the BCL? Do you have the same problems with designing types?

API Design: The why of "StringBuilder.AppendFormat()" design

KathyKam — Fri, 12 May 2006 04:38:00 GMT

"Why does StrignBuilder.AppendFormat() need anything more than AppendFormat(string, object[])?" -- Curious StringBuilder.AppendForamt user

This is a great question. Before I begin, let's visit what overloads AppendFormat has....

AppendFormat( string, object);
AppendFormat( string, object, object);
AppendFormat( string, object, object, object);
AppendFormat( string, object[]);
AppendFormat (IFormatProvider, string, object[])

An obvious question is, why do we need the first three (the ones in blue)? (Obviously, we need the one with IFormatProvider...)

Here is what I learnt:

1) Some languages doesn't support "params" syntax. By having those overloads, we allow a short cut that allow the developer to directly use it without having to create an array.

2) Allows the option for the CLR engine to do performance optimization (without array creation or other optomization) on common scenarios. (However, the CLR engine has not taken up on this option...)

<editorial comment>
In the past 5 months on the BCL team, I have learnt alot about design decisions made on the current BCL APIs and some of its consequences. Many times, the lessons of poor design does not show up until you have ship multiple version of the APIs. I think I am gonna start sharing some of the stuff I picked up from the team on this blog. Since V1, the BCL team has lots of experiences to share. A lot of successes, and some failures ;). (By the way, if you don't know already, Krzysztof and Brad did a great job of sharing some of the successes and failures in his Framework Design Guidelines book. It's a great read! The BCL team is the Guidelines' first customer, and I find VERY intersting to learn how the BCL APIs relates or drive these guidelines.) Anyways, my first post on this topic is not really a "lessons learnt", it is more a "I always wonder why....".
</editorial comment>

If you have any "I always wonder why the BCL did <Some API> this way...", please send it to me. I'd love to find out and share with you.

Feature Requests... why don't we just do them all?

KathyKam — Tue, 18 Apr 2006 18:00:00 GMT

Today, I learned an intersting (and very important) lesson about building a framework. I was in a meeting where another team wants the BCL's support to add some APIs to WinFX. The APIs they want to add are valuable. It gives power to .NET developers to do something new, it opens new doors. It seems brain-dead obvious that they should be allowed to add it. As a matter of fact, sometimes, when I look over the 1100+ feature request on the BCL team, it feels brain-dead obvious that we should do every single one of them. Our users usually have great feedback, and many of them does make it into our feature request database. However, we do not do all of them. Our users may ask... why? why not?

Well, the main reason is because we have limited resources. Every feature, change, bug fix takes time, energy and effort. This is relevant in all products Microsoft ships. Back in my Outlook days, I faced the same problem. (Should we fix a bug that causes meeting to drop off on your calendar or a bug that cause reminders not to fire?) Every group in Microsoft take great care to make sure that we are using our resources most efficiently. With limited resources, we try our best to deliver the most value to our customer. This means delivering the most important, the most painful to live without feature first. That's why the question Krzysztof asked in the BCLTeam Weblog was very interesting. He didn't ask "What do you want in the BCL?", he asked "how would you spend the limited resource (fake BCL brownie points) you have?"

Today, I learned a second reason. Even if we have unlimited resources, armies of testers and developers to do these feature requests (Like this group that is willing to pony up the PMing, Deving, and Testing of their favourite feature), why in the world would the BCL/CLR even consider not approving it?

Sometimes, less is more. This is particularly true when it comes to anything that interact with users. It doesn't matter if it is the framework or the UI.

A framework with multiple ways of representing a string (ahem.. anyone remember those bstr, char[], wchar[], etc... ) causes confusion. When I was a developer in Outlook, every file has its own version of string. Instead of opening new doors, allowing new ways of coding, this actually slows developer productivity. Who wants to use a framework that you can't tell what to use and why? A bloated framework is unmanageable. Similarly, a overly crowded UI is unmanageable. That's why Office has decided to design the ribbon. I am not going to go into UI design in this blog. I leave that to my friend Jensen, UEX PM lead (also an ex-Outlook PM), who wrote "Why of the New UI" series to explain the problems of the overcrowded UI that plagued Office users.

What do you think? Agree? Disagree? When you design your software, have you ever decided not to put something in it because "Less is More"?