Udostępnij za pośrednictwem

Naming Guideline Discussion

  • Artykuł

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

Check it out: https://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.

Comments

  • Anonymous
    October 06, 2006
    Right now, there is no easy way to convert a time from one arbitrary timezone to another arbitrary timezone

  • Anonymous
    October 07, 2006
    The comment has been removed

  • Anonymous
    October 10, 2006
    Ever since Kathy Kam announced on her weblog that a new type named TimeZone2 will be introduced into

  • Anonymous
    October 10, 2006
    What about TimeRegion? Regards

  • Anonymous
    October 11, 2006
    Hi Kathy. Interesting topic. I've got a suggestion to sidestep the whole -2 suffix completely. This new class doesn't really add any new functionality to TimeZone. The TimeZone class describes an actual time zone, and (as I understand it) the new functionality is to return an instance of TimeZone based on an id (factory pattern), get a list of known time zones and to convert from one timezone to another. Creating a TimeZoneFactory class could solve both the first and second problems and a TimeZoneConverter class would solve the other one . Any other methods that add functionality to TimeZone itself can be added on - adding methods/properties isn't a breaking change. A method on TimeZone could be used to convert a date from one timezone to another. This solves your versioning problem, and also keeps the responsibility of TimeZone(2) to a single responsibility. What do you think? And conversely, what was the thinking behind adding these extra responsibilities to TimeZone(2)? Cheers! Matt

  • Anonymous
    October 11, 2006
    Hi Matt, Thanks for the suggestion! However, this is incorrect... "Any other methods that add functionality to TimeZone itself can be added on - adding methods/properties isn't a breaking change." Actually, we changed the behaviour of methods like IsDaylightSavingTime. Read Part 2 of my "Desiginng TimeZone2" for more detail. If you have more questions or comments after that. Please let me know. Regarding adding these extra responsibilities to TimeZone2. Once we realize we need a new type regardless, we need to make a decision on how many new types we should add. We decided to add one. Usability studies shows that it is easier for our users to deal with only one type for all their need. That said, I want to emphsis that API design is all about tradeoffs. No one design is perfect, and there are of course arguments to say 2 (or even 3) types are better. I'd love to know why you think 2 or even 3 types are better than 1! Thanks, Kathy

  • Anonymous
    October 12, 2006
    When you see TimeZone and TimeZoneInfo next to each other in intellisense, how do you know which one to use? If you say TimeZone and TimeZone2 next to each, I think it is a lot more clearer that TimeZone2 is the later version.

  • Anonymous
    October 17, 2006
    Glad you think TimeZone2 is better! :) I wonder does anyone else thinks it is better.

  • Anonymous
    November 24, 2006
    Kathy, I read the guidelines and I think the TimeZone2 name is the least harmful ;) Anyway, what I don't find explained in detail is why you had to create a new type instead of "stuffing" the new features in the original class (and possibly marking part of its remains as obsolete). I am sure it was because you found some road block there and not because of a matter of taste. What was it?

  • Anonymous
    November 24, 2006
    Ah, now I read your comment. So you changed behaviors... I will read the rest in your "Designing TimeZone2^2" ;). Thanks!

  • Anonymous
    January 03, 2007
    @David M. Kean & Kathy: if you insist that TimeZone2 beats  TimeZoneInfo in indicating it is a "new" one, how about putting Obsolete attribute to TimeZone to imply that it is an "old" version of TimeZoneInfo? Just imagine some day they want to "upgrade" such things as Int32... there you go, we got Int322 !!! Now, tell the innocent why it is "Int32 version 2" but not "Int version 322" ???