Рекомендуется к прочтению:
http://chaos.troll.no/~shausman/api-design/api-design.pdf тем, кто еще не читал. :)
This manual gathers together the key insights into API design that were discovered through many years of software development on the Qt application development framework at Trolltech (now part of Nokia). When designing and implementing a library, you should also keep other factors in mind, such as efficiency and ease of implementation, in addition to pure API considerations. And although the focus is on public APIs, there is no harm in applying the principles described here when writing application code or internal library code.
[Qt!] Examples from Qt’s history are presented in blocks like this one. If you are new to Qt, you might find some of these examples obscure. Don’t hesitate to ask your colleagues for details. Also, many of the examples come from classes on which I worked, for the simple reason that I know those best. Other classes could have provided just as good examples.
abbra
В этом смысле интересным продуктивным подходом было бы целенаправленное планирование API на некотором нереальном языке, без практического использования, а потом последовательное уменьшение получающегося вывода на целевой язык программирования. Интересно, насколько такую задачу минимакса можно автоматизировать?
По-моему, куда более правильным подходом является использование для описания сложных API вполне реального языка. Но не С или C++, а чего-нибудь вроде Python. Где есть необязательные паркметры, ключевые параметры, списки, tuple и прочее и прочее.
Использование реального языка предполагает, что прогнозируемое API будет изначально учитывать семантические особенности этого реального языка. Вот такого хотелось бы избежать.