Why is the function SHStripMneumonic misspelled?


If you wander through MSDN, you may stumble across the function SHStripMneumonic. The correct spelling is mnemonic. Why is the function name misspelled?

"It was like that when I got here."

The function was originally written for internal use only, and the person who wrote the function spelled the word incorrectly. Still, since it was an internal function, there was no real urgency to fix it. After all, there is no technical consequence of the spelling of a function's name, as early entrants of the IOCCC discovered. If you really wanted to, you could just call all your functions F1 through F578173.

There the function remained, misspelled but inconsequentially so, for some time. Since it was an internal function, it didn't go through the normal scrutiny that a public interface receives. That's part of what makes it internal.

The effort required to fix the spelling was a bit more than usual, since the function was used by multiple teams, so there would have to be some coordination among the teams so everybody fixed their spelling at the same time. The issue sat on the back burner as a very low priority item since it wasn't hurting anybody, and the effort required to fix it really didn't justify the benefit (which was zero).

In 2001, the order came down to document all functions which met specific criteria (the details of which I will not go into, and I would appreciate it if others didn't try), and the SHStripMneumonic function was suddenly thrust onto the public stage before it had a chance to so much as comb its hair and make sure it didn't have food stuck in its teeth. The function had to be documented, warts and all, and the bad spelling was one of the warts.

Of course, now that the function has been published, its name is locked and can't be changed, because that would break all the programs that used the original bad spelling.

Epilogue: Some commenters are suggesting ways that the function could have combed its hair and removed food from its teeth, completely ignoring the point that the function had to be documented, warts and all. I assure you, nobody wanted to comb that function's hair more than me.

Comments (43)
  1. Jon says:

    The authors of the HTTP spec misspelled referrer. So for the rest of eternity (or until they break backwards compatibility) it is a referer.

  2. PinkDuck says:

    I’d say the benefit of fixing the typo is more than zero, as it stops annoying developers who can spell, makes the name more guessable, allows for searches on ‘mnemonic’ to be more inclusive, and most importantly is one less character to type :)

  3. A good solution would be to have offer both APIs, and mark the misspelled one as deprecated.  Then after a few releases of the compiler and/or OS remove the original misspelled version.

  4. What prevents the creation of SHStripMnemonic with the same arguments, and just have it be an alias for the misspelled version?

  5. BryanK says:

    Brian: You’d have to leave the misspelled version exported from the DLL forever; not everyone rewrites their code whenever a new OS comes out.

    You could, of course, fix the spelling in the public SDK (the header files, possibly the .lib file, etc.) after a few releases of the SDK where the wrong spelling is deprecated.  (You could even have the misspelled DLL export be a forwarder to the correctly-spelled export, so people spelunking in exports rather than reading the documentation might get a clue.  And of course you wouldn’t want two copies of the implementation, so you’d probably want to do this anyway.)

    But sadly, you can’t rely on everyone recompiling everything after any length of time, so I don’t think you can ever remove the misspelled export…

    (Plus, what about VB6 or .net programs that call the misspelled name, but which never get compiled against header files?  The DllImport attribute and the Declare Sub VB6 stuff both call a DLL function by its exported name; there’s no way to indicate that these programs will ever need to be changed.)

  6. Alexander Grigoriev says:

    Somebody in SDK team have never heard of #define and DLL name forwarding (which would resolve old name).

    On the other hand, those many functions in shlwapi should have never be exposed to outside world, as they’re shamefully badly designed. Think of that, a function that doesn’t have an output buffer size argument.

  7. Anonymous Coward says:

    There’s also the famous Unix API function creat()

  8. SM says:

    Why do you need the SDK team to #define it with the correct spelling? You can do that all by yourself.

  9. vsz says:

    Come one, MS folks! You could add a corrected one as a duplicate with the same functionality, convert the old one as a wrapper (or vice versa), move the misspelled one deprecated compatibility status and you’re done…

  10. James says:

    This is all actually a cover story; in reality, the function is a hook for an anti-virus product, which was supposed to be spelled SHStripPneumonic and is intended to quarantine dangerous plague-carrying objects before they can affect the user.

  11. mikeb says:

    I can never remember how to spell mneumonic.

  12. Yuhong Bao says:
    [Yuhong Bao proceeds to raise a topic I specifically called out as “the details of which I will not go into, and I would appreciate it if others didn’t try.” I was afraid this would happen. Another category of blogging disappears from the queue. -Raymond]
  13. Starfish says:

    Anything that arises or could possibly be connected to various Microsoft misdemeanours seems to attract this (sadly not pre-emptive-enough) snarky comment:

    "I have a bone to pick with Microsoft, so I will knowingly annoy one of their bloggers by encouraging them to bring up a dead horse everyone has long since beaten to death. Oh no, the blogger won’t play ball and has punished us all for doing what he told us not to. Obviously he is in the wrong."

    I would rather see the comments disabled and stop things like the above than for future blogs to be purged.

    On a related note, I guess the SHStripMneumonic function had to be exported with that name because of aforementioned reasons? Not that there is anything to prevent a #define, of course, but I hazard a guess that even adding a simple #define is not trivial if it needs to go through several reviews first. At a time when lots of functions had to be documented, fixing the typo was probably more frivolous than anything else.

  14. SteveL says:

    For us UK programmers, most APIs are wrong, everything with Color or Center in them, for a start. So one more accidental error is neither here nor there.

    We have had lots of fun in Apache Ant where the error message "you have misspelt your task" kept on generating lots of bugreps saying "you have misspelled misspelt" which we would file as invalid on account of EN_GB locale using "misspelt". Eventually we got bored of this and switched to the some locale-neutral message like ‘typed it in wrong’. There goes our attempt to push back with UK spellings.

  15. /.er says:

    I have a (non-technical) query and I’ve noticed the suggestion box has been closed for several months. Is the backlog too great / spam to voluminous for it to be reopened or does it just open for a very short period of time?

    [Like it says: “Note the enormous topic backlog. Consequently, the suggestion box has been closed temporarily and will reopen once the existing backlog has cleared, which I estimate will happen sometime in early 2010. If your suggestion is that important, I’m sure you’ll remember it when the suggestion box reopens.” -Raymond]
  16. Wang-Lo says:

    "If you really wanted to, you could just call all your functions F1 through F578173."

    Be careful!  Some poorly trained cargo-cult coder will do this and then tell everyone that you said it was all right.

    -Wang-Lo.

  17. JamesNT says:

    Pre-emptive answer to obvious question:

    No, it is NOT acceptable for Mr. Chen to make more blog posts a day than what he already does and it is NOT acceptable for him to post on the weekends.  Like the rest of you, Mr. Chen also has a private that he would like to devote time to and also has a full-time job that requires a great deal of time.  

    JamesNT

  18. Joe Butler says:

    JamesNT: "Mr. Chen also has a private that he would like to devote time to…"

    A private what?!

  19. Fifth Amendment says:

    "If you really wanted to, you could just call all your functions F1 through F578173."

    I used to work for a company as a manager, and we were developing a COM interface and the person that was the "Expert" came into the managers office and convinced 2 out of three mannagers to do this very thing, because COM interfaces once written couldn’t be changed.  I didn’t buy his arguments but the other managers did, so for about 6 months the DLL’s for this project exposed function0 through function25.  

    It was about then that the flaws became apparent to the other managers, they were trying to trace a bug and the "anonymous" functiona made it near impossible.

  20. Daev says:

    "I was afraid this would happen. Another category of blogging disappears from the queue."

    Please let me encourage you not to choose the stock of your china shop solely on its bull-resistance, especially when you have just put that bull out to pasture.  The history of this blog has shown that people’s behavior does improve; just take a trip back to 2004’s comments to see what I mean.  I enjoy these excursions into quirkiness and would like to see them continue.

  21. Dmitry Kolosov says:

    @SteveL

    For us UK programmers, most APIs are wrong, everything with Color or Center in them

    Just imagine how wrong it is for us Russian programmers. AmEng and BrEng just happen to be similar enough to make you think it’s the same language :-)

  22. KJK::Hyperion says:

    Public APIs aren’t always exempt:

    http://msdn.microsoft.com/en-us/library/aa506097.aspx

    "Note that these two names are misspelled, but are consistent with the names that appear in the header file, winsplp.h"

  23. Anon says:

    Great…

    – Say something intriguing

    – Ask people not to talk about it

    – Sulkily take your ball home when the totally inevitable happens

    Why do you do this? Repeatedly?

    [Because I never learn my lesson. Perhaps I should run my topics past you, and you can tell me which ones are “intriguing” and therefore should be avoided. -Raymond]
  24. JamesNT says:

    @Joe

    A private LIFE!!  Yes, I left out a word and apologies but surely we could all fill in the blank on that one with our dignities intact.

    JamesNT

  25. Fifth Amendment says:

    MadQ,

    I apologize to have given the impression, but I wasn’t nitpicking, I forgot to include Wang-Lo’s comment: "Be careful!  Some poorly trained cargo-cult coder will do this and then tell everyone that you said it was all right."

    It was in response to the Comment from Wang-Lo to show that it has already happened, but the blame was put on Microsoft documentation.

    I won’t say too much more about that situation, except I did argue that this "Expert" was making a terrible suggestion.

    It did make sense to standardize the names for this project, as it was using COM for a plug-in frame work, but even if his arguments were true there were better solutions.

    Again, I apologize for the impression of nit-picking, and I fully appreciate the points Raymond is making.

  26. x says:

    > I was afraid this would happen. Another category of blogging disappears from the queue.

    Please don’t.  Just disable comment on these posts.  

  27. Neil says:

    Are you sure that SHStripMneumonic is not actually a mis-spelling of:

    SHStripPneumonic

    Removes a lung from a human being.

    Syntax:

    BOOL SHStripPneumonic(LONG painTolerance, void *human);

  28. Larry Hosken says:

    As a professional technical writer, I must point out that there is only one solution for this problem: more jargon.  Specifically, you need to convince people that "mneumonic" means something.  I suggest one of the following definitions:

    1. A mental trick for remembering which menu a menu item appears in.  E.g., "Cut, Copy, Paste, Undo; Under edit, one two. In File, here’s a hint: Save, Export, Close, Print"
    2. A mental trick for remembering what the f57183 function does.

    3. It means… the thingy that SHStripMneumonic strips.

    Soon, everyone will be saying "mneumonic" all the time, probably in meetings.

  29. steveg says:

    I am thinking of writing about this on my own blog, and putting a link to it from here. Is that OK? I’m sure I can, since it is my own blog.

    Why don’t you actually use your brain, and since you’re clearly pretty impressed with the capabilities of the one you have, the answer should be obvious whether that would be appreciated (although I am actually impressed you asked, perhaps you are learning how to intereact with adults).

    I would remind you, Yuhong Bao, you promised to stop posting here. It’s a pity you don’t keep your promises.

  30. Peter says:

    MADQ: Actually, "COM" isn’t strictly binary.  Any time you want to make your handy-dandy COM object visible to Javascript, you need to start making IDispatch() thingies — and those do make use of the actual string of the name.

    (You might argue that "that isn’t COM" — but you’d be wrong. COM is an entire ecosystem and not just a fancy word for VTable)

  31. MadQ1 says:

    "…because COM interfaces once written couldn’t be changed."

    Did anyone tell them that a COM contact is strictly binary? COM doesn’t care about names. Of course the semantics of an interface might say differently (a la IDispatch). The semantics are just the rules above and beyond COM. It’s up to the designer of the interface to communicate them.

    Anyway… as long as the function stays in the same slot in the vtable, you can rename it till the cows come home. It’s actually done fairly frequently when using the CLR and COM InterOp.

    Now, whether renaming things willy-nilly is a good idea, is an entirely different topic.

    Geez, so much for a quick one-liner comment. Damn nit-pickers!

    Regarding disappearing categories: *sigh* there’s just always that one person who just _has_ to p^Hrelieve themselves into the erm… liquid food.

  32. Dean Harding says:

    Peter: But you can write your IDispatch interface to take any value you like as the "name" and call whatever you like. "Foo" by IDispatch might call a totally different method to "Foo" by the VTable…

  33. Dean Harding says:

    And just FYI, I’m certainly not advocating that anybody actually does what I suggested in the comment above :p~

  34. stdout says:

    That’s why he codes in C++, so he can keep his private members strictly private.

  35. Mike Dimmick says:

    @KJK::Hyperion: I suspect that was a note to the copy editor not to correct the spelling, which was left in the final copy.

  36. AndyC says:

    @JamesNT, yes it was obvious you meant "Life", but "Detective Agency" sounds so much more exciting! ;-)

  37. Markus says:

    In my experience, when working on *internal* projects, having to document the "warts" is the best time to remove them: it is often easier to fix strange/erroneous/unpredictable behaviour, mistyped names, and "holes" in the API than to document them.

    Of course, you can’t do this easily in an API that is already baked into DLLs that are deployed in production programs.

  38. Anon says:

    [Because I never learn my lesson.]

    I regret thus far you are right.

    [Perhaps I should run my topics past you, and you can tell me which ones are "intriguing" and therefore should be avoided. -Raymond]

    I can save you some time with a simple rule — give up immediately on anything where you feel the need to say "please don’t discuss this in the comments", or similar.

    Don’t take it personally. Just tedious to see this happening repeatedly. Your blog is sensational.

  39. Lauren Smith says:

    Shouldn’t that be "SHStripPneumonic"?

  40. SuperKoko says:

    I don’t think fixing the typo is worth it.

    A simple #define cannot solve the compatibility problem. Win32 isn’t bound to the C and C++ programming languages. It defines an ABI.

    So, if a transition from the old name to the new name had to be performed, the DLL would have to export both symbols (SHStripMneumonic and SHStripMnemonic), at least for a long time. Most probably forever.

    A typo isn’t important, in my opinion. It doesn’t kill kittens.

    "There’s also the famous Unix API function creat()"

    creat was intentionally misspelled, most probably because UNIX creators don’t like vowels and like very short names such as ls or ln, maybe because interactive typewriters were painful to use…

    In my opinion, this name has advantages. It’s easier to search on google or on a web page than create() would be. By using a different pronunciation, it’s easy to unambiguously talk about this function.

  41. Koro says:

    Sometimes when reading the SHLWAPI docs it makes me feel somebody in the shell team loves to reinvent the wheel :)

    Just look at all the StrXxx functions (are kernel32’s lstrxxx or msvcrt’s strxxx/wcsxxx functions not good enough?), or other functions that seem to just wrap another API function (example, the SH-Registry functions; although for all of these, one can assume that they were put there for Win9x compatibility, a.k.a on Win9x they did more to emulate NT behavior and/or support Unicode).

    [What locale do strxxx/wcsxxx operate in? The answer may surprise you. -Raymond]
  42. Koro says:

    [What locale do strxxx/wcsxxx operate in? The answer may surprise you. -Raymond]

    My assumptions (pulled *totally* out of nowhere):

    – kernel32’s lstrxxx: (w)char-per-(w)char-wise comparison/copy

    – msvcrt’s strxxx/wcsxxx: using the C locale per default, unless overriden in the thread using setlocale (which can be a problem if not all the running code in the thread can be guaranteed to not change it under the rest of the code’s back, such as in shell extensions or other plugins)

    But another one I forgot: NTDLL has it’s own mini-CRT, but I assume this one would be simplistic enough to not care about code pages and just operate on (w)chars blindly…

    Which then reminds me, if I can’t assume all the C string functions will be deterministic because they are not "blind enough", I’ll have a few 50000-line projects to search-and-replace the calls to dumber ones :(

Comments are closed.

Skip to main content