Who does actually read the API documentation when it comes to setting a simple property like the one named Text in System.Windows.Forms NotifyIcon? An API that is used by hundreds of applications. Would you expect that this unsuspicious setter could throw you an exception?
You may think perhaps in some really “exceptional” situation, when there is no Shell anymore or the System is shutting down.
No, it throws an exception if the text exceeds 63 characters. Wow, imagine that a lot of tooltip notifications are built by string.Format() or just extracted from resources that may be translated to different languages.
The API designer could argue that “hey, it’s documented, and I have no idea what to do when your request can not be fulfilled”. Though I consider this argument as valid, for most applications, an exception while setting user interface elements is mostly unhandled and so crashes the application. Boom. An bomb went off, caused by an API that reflects an unexpected system or formatting limitation back into your application.
I am stating that this is a leaky abstraction. And if there is a string to set somewhere, and its property name looks unsuspicious, I’d expect the API to handle ANY string. As an application programmer, I don’t care about a system limitation or a formatting nuisance. Even when the string can not be displayed as expected, a more preferable API would append some ellipsis, truncate the text, or display the tooltip by some other means.
I personally would find the following API design decisions acceptable (in order of preference):
Application programming should be different to systems programming. Application APIs should be designed so that the correct use can be derived by just looking at their signature.
Think about how often you used some property without going through all the documentation. In each of them may hide a bomb.