Share via

API Naming - API Design

  • Article

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?

Comments

  • Anonymous
    September 26, 2006
    "So, can you guess which two names was the most debated names on the BCL?" I'm guessing NameValueCollection, ListDictionary, StringDictionary... I have to look the differences up in the MSDN Library each time I need to use them. They have very unclear names.

    I have the same problem with my API's and I sometimes find it very difficult to reconcile the 'Name should not be "close enough"' guideline with the 'Names should be as short as possible' guideline. Sometimes you just need 4 or even 5 words to describe a class or a member in sufficient detail.

  • Anonymous
    September 26, 2006
    Hi Michael,

    Nope, actually NameValueCollection, ListDictinary, StringDictinary are not the most debated names. The names that were most debated was actually pretty clear now that we think about it. It was just contentious.

    I agree that it is hard to reconcile being short yet not being "close enough". What I want to highlight about not being "close enough" is not be incorrect. It might be better to have a shorter more ambiguous name than a long clear name. However, you should never have a short (or long) incorrect name.

    Cheers,
    Kathy

  • Anonymous
    September 26, 2006
    TextReader has to be one of them.

  • Anonymous
    September 26, 2006
    Hi Robert,

    Nope, TextReader was not one of them. Why do you think it must be? Do you dislike the name?

    Cheers,
    Kathy

  • Anonymous
    October 03, 2006
    Didn't I say it two weeks ago that API naming is the most difficult thing? :) My BCL post on System.TimeZone2

  • Anonymous
    October 06, 2006
    Yeah.. Krzysztof have finally blogged about the controversial naming guidelines around TimeZone2! Check

  • Anonymous
    October 24, 2006
    <em><b><u>An</u></b> UTC Offset</em>? Do you pronounce UTC as "ootech" or something?