A way better model for features, part 2

by Michael S. Kaplan, published on 2007/03/19 06:31 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2007/03/19/1912171.aspx

You may have seen the first part of this series (A way better model for features). Think of this as part 2....

This time I am going to use as a victimexample the Microsoft National Language Support Downlevel APIs 1.0, which I have talked about previously in posts like this one.

Now I am not going to complain about the fact that they are tagging a small subset of functions from the NLS API as "APIs", though clearly someone is not paying attention to the fact that API stands for Application Programming Interface, and thus a function is not an API, and neither is a small set of functions APIs, plural.

But this is just one of those minor language issues I try not to become all mavenesque about. And the other reason I won't complain about this is that I used to make the same mistake. I don't anymore and I hopeful that all of my colleagues will come to the same realization one day. :-)

To see what my complaint is, let's look at the functions in this library:

  • DownlevelLCIDToLocaleName - converts an LCID to a locale name.
  • DownlevelLocaleNameToLCID - converts a locale name to an LCID.
  • DownlevelGetParentLocaleLCID - retrieves the parent LCID for a locale.
  • DownlevelGetParentLocaleName - retrieves the locale name for the parent of the indicated locale.
  • Now let's compare that little set of functions to the ones they replace in the downlevel situation:

    At this point, you may see what the problem is -- you need to write two different kinds of code to use the two different functions!

    Do what is the benefit to use locale names downlevel if all of the code that is going to be written has to be special cased anyway? There is no real benefit to moving the code to use names here, one may as well either

    1. have the special case code use LCIDs downlevel and names on Vista, or
    2. just stick with LCIDs on all platforms.

    Since the whole goal of nlsdl.dll is to try to make sure people don't do #2, this particular set of functions fail the basic requirements that led to the DLL being created.

    A much better model here is code that can look identical on all platforms. What I would do is one of the following, instead:

    This way, there is a good and easy way to write the new code, not the old code. To use names and not LCIDs. And there is no eventual fear of needing to revisit code based on changes.

    To be honest, I would extend the model and add stub versions of all of the locale name based Ex functions added in Vista (discussed previously here) and put them in that same library. Because no one is going to want to write "If on Vista do this entirely different operation" type code, so the best thing to do is add these wrappers and call it a day.

    The existing DLL is simply not such a hot model for helping developers migrate to using locale names rather than LCIDs....

    So it looks like MSLU wins again, this time when it comes to model decisions for migration and giving developers a clean migration path. Barry Bond wrote the first prototype that did this for MSLU, so I am technically just saying it is Barry's ideas that trump nlsdl.dll's ideas, not mine. I just had the good luck to be the one to take his prototype and run with it. :-)


    This post brought to you by (U+1009, a.k.a. MYANMAR LETTER NYA)

    # Miral on 21 Mar 2007 8:56 PM:

    The use of "APIs" in that context is really just an abbreviation for "functions from the API".  I don't consider it a mistake.

    # Michael S. Kaplan on 21 Mar 2007 9:44 PM:

    Hmm.... I don't think that "APIs == functions from the API" is a natural thing here.

    Though as I pointed out that is not why I'm upset here, not where I think the failure lies....

    referenced by

    2010/11/08 Header files are the wrong place to be less than helpful

    2007/06/11 LCID vs. Powerman and the Locale-name-go-round

    2007/04/29 A way better model for features, part 3 (a.k.a. downlevel LoadMUILibrary)

    go to newer or older post, or back to index or month or day