API Naming - API Design

re: API Naming - API Design

Michael Vanhoutte — Tue, 26 Sep 2006 15:50:26 GMT

"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.

re: API Naming - API Design

KathyKam — Wed, 27 Sep 2006 00:11:46 GMT

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

re: API Naming - API Design

Robert Kozak — Wed, 27 Sep 2006 01:02:50 GMT

TextReader has to be one of them.

re: API Naming - API Design

KathyKam — Wed, 27 Sep 2006 03:45:13 GMT

Hi Robert,

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

Cheers,
Kathy

Interesting Finds: September 26, 2006

Jason Haley — Wed, 27 Sep 2006 06:48:20 GMT

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

Kathy Kam — Wed, 04 Oct 2006 08:23:27 GMT

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

Naming Guideline Discussion

Kathy Kam — Sat, 07 Oct 2006 03:57:54 GMT

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

re: API Naming - API Design

asqui — Tue, 24 Oct 2006 17:17:42 GMT

An UTC Offset?

Do you pronounce UTC as "ootech" or something?