The Little Manual of API Design

[abbra]

Рекомендуется к прочтению: 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.

Comments

[vitus_wagner]

А-А-А! HIG для интерфейсов разработчика.

[abbra]

Примерно год назад я прошелся по VAPI файлам для GTK+ и обнаружил, что практически везде идеи в API довольно хорошо прослеживаются и не противоречат принципам, подобным описанию в The Little Manual of API Design. При этом если смотреть на представление того же API в C, для некоторых нетривиальных вещей глаз просто отказывается эти идеи парсить.

В этом смысле интересным продуктивным подходом было бы целенаправленное планирование API на некотором нереальном языке, без практического использования, а потом последовательное уменьшение получающегося вывода на целевой язык программирования. Интересно, насколько такую задачу минимакса можно автоматизировать?

[vitus_wagner]

Ну это, всяких IDL уже наизобретали. По-моему, идея реализации отдельного языка описания интерфейсов на примере всяких Corba и прочих Active-X давно и надежно показала свою бесперспективность.

По-моему, куда более правильным подходом является использование для описания сложных API вполне реального языка. Но не С или C++, а чего-нибудь вроде Python. Где есть необязательные паркметры, ключевые параметры, списки, tuple и прочее и прочее.

[abbra]

Не, большинство этих IDL рассчитаны на отражение API в какой-нибудь протокол передачи данных, вроде ASN.1 или подобных осложнений. В результате, IDL получается описывающим структуры данных, а не семантические реляции между методами и данными.

Использование реального языка предполагает, что прогнозируемое API будет изначально учитывать семантические особенности этого реального языка. Вот такого хотелось бы избежать.