API Naming - API Design

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?