Raymond on helper functions
Working on the Visual Studio Tool Platform team, we do a lot of work on making VS extensible and providing infrastructure for other teams to build on top of (some of our work is end user feature work as well, it's an interesting mix of things). We have to balance the exposure of the APIs and tying ourselves to one implementation. The key takeaway from the article for me was:
Why does such a confusing function exist at all? Well, the shell team thought they were doing you a favor by providing this function back in the 16-bit days. This was originally an internal function used by (I think it was) File Manager, but since it solved a more general problem, the function was exported and documented. In the intervening years, the problem it addressed has been solved in other ways, and the introduction of 64-bit Windows rendered the original solution unworkable anyway, but the function and the code behind it must still linger in the system for backwards compatibility purposes.
The shell team learned its lesson. It no longer exports every little helper function and custom control for third parties to use. If a future version of Windows no longer needs the helper function, or if a redesign of Windows Explorer removes the need for that custom control (or worse, changes the behavior of that custom control), the shell would still have to carry all the code around for the unused function or control because a function, once documented, becomes a continuing support burden.
Read the entire article here: http://blogs.msdn.com/oldnewthing/archive/2007/07/10/3799014.aspx