Лучшие практики и инструкции для разработки [закрытого] API

Как человек, которому приходится потреблять тонны API ...

Пожалуйста, напишите свой API последовательным образом:

1. Согласованное именование внутри самого API. Используйте глаголы, существительные и ключевые слова ТОЧНО в одном стиле.

2. В соответствии с целевой средой, в которой он будет использоваться. Если .NET, то обратитесь к руководству Microsoft по именованию.

3. Последовательные концепции. Заводской образец? Выкройка строителя? Статические методы? Интерфейсы? Просто выберите один и придерживайтесь его. В САМОМ ДЕЛЕ. Не существует такого понятия, как небольшое исключение из правил. Он будет торчать как большой палец. Более одного исключения? Ваш API становится все более любительским.

Вот еще один: Специфика.

1. Базовые классы, которые я могу реализовать, если вы решите их предоставить, должны иметь несколько четко определенных функций для реализации. Не говорите мне, что «GetData ()» возвращает «объект []», а затем ожидайте, что я его реализую, выясню, почему я должен преобразовать его в строку [], а затем отладить, почему он вызывается 20 раз. Намного лучше иметь DataPoint [] GetChartData (), string [] GetLabelData () и т. Д., И я могу выбирать, какие из них мне следует реализовать.

2. Пожалуйста, не делайте глупых длинных имен: PostRenderColorWheelModifyHSVBaseHandler. Вы можете часто реорганизовать сверхспецифические вещи в более общее имя + параметры.

3. Строковые параметры запрещены! Используйте перечисления. Я не хочу использовать обработчик вроде

   PostRenderHandler ("ColorWheel", "HSV", someDelegate);

Я бы предпочел перечисление, которое я могу исследовать:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

Чувак, я мог бы продолжить ... Мощь этого парня Джоша Блоха - хорошо написанные API могут быть действительно крутыми ... плохие могут быть очень болезненными.

Это ссылка от Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

Также есть эта книга: {{1} } Рекомендации по разработке инфраструктуры: условные обозначения, идиомы и шаблоны для многоразовых библиотек .NET

Есть хорошая презентация на эту тему от Джошуа Блоха. В презентации используется Java, но идеи не зависят от языка. Другой источник (pdf) для быстрого обзора.

Я думаю, что на ваш вопрос не будет ответа в таком объеме места с объемом информации, который вы даете. Я поместил несколько ссылок, набрав "api design" в Google, и на первой странице они выглядят довольно неплохо

http://web.archive.org/web/20151229055009/http://lcsd05.cs. tamu.edu/slides/keynote.pdf

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

http://web.archive.org/web/20090520234149/http: //chaos.troll.no/~shausman/api-design/api-design.pdf