Что общего у замечательных API? [закрыто]

Что хорошего в API, что делает их великолепными? Я думаю, что придерживаться мантры «делай одно и делай хорошо» - это хороший знак, а быть хорошим отображением проблемной области важно, но что общего у хороших API?

Вы должны быть осторожны, чтобы не добавлять новый словарь только ради вашего API. Мои любимые API объясняют мне слова, которые я уже понимаю. В том же духе:

Не добавляйте слишком много абстракций поверх того, что вы строите. Будь проще.

Я уже должен думать о полдюжине слоев абстракции. Не заставляйте меня думать о дополнительных слоях. Не давайте мне слишком много новых вещей, чтобы учиться, которые не добавят ценность моей конечной цели. Например, избегайте использования своего собственного специального класса файлов, который работает иначе, чем тип файла языка, потому что вы думаете, что ваш путь лучше, чем общепринятый способ. Придерживайтесь общепринятого способа, по крайней мере, в ваших интерфейсах, к лучшему или к худшему.

Придерживаться конкретных идей

Например, не пытайтесь скрыть тот факт, что «модельная» часть вашей инфраструктуры MVC является внешним интерфейсом для базы данных. Воспользуйтесь хорошо известным словарем, окружающим «базы данных». Я знаю, что такое внешние ключи. Я знаю, что такое строки и столбцы. Поговори со мной в этих условиях.

Не абстрагируйте необходимые знания

Похоже на работу с конкретными идеями. Не скрывайте, что мы имеем дело с файлами, базами данных или строками в базах данных. Я знаю эти вещи. Если я имею дело с контейнером, таким как List, есть хороший шанс, что мне нужно знать алгоритмическую сложность обычных операций. Вы можете упростить это, просто сказав мне «связанный список» или «массив». Огромный набор идей внезапно будет связан с тем, что вы делаете, и все это внезапно обретет смысл. Не создавайте свой собственный набор идей, которые я должен выучить, когда я уже приду с богатым и полезным набором терминологии для применения к проблеме.

Сократить количество терминов, которые мне нужны в моем словаре

Если я использую ваш API для открытия файла изображения любого типа, мне не нужно слишком много думать о pngs vs gifs vs jpgs. Ты сделаешь это для меня. Это ваша основная компетенция, а не моя. У меня есть смутное понимание, что у тебя есть немного магии, чтобы сделать это для меня.

Полезный API имеет следующее:

• Краткая и тщательная документация. Если я ищу способ реализации задачи, я могу узнать, есть ли у API возможность сделать это, в течение нескольких минут. Это достигается за счет краткости текста и разметки ресурса. Документация содержит примеры того, как его использовать, а также не делает никаких предположений относительно читателей.
• Большое, активное сообщество. Меня радует, когда я нахожу форумы, IRC-каналы, списки рассылки и т. Д. С активными участниками, готовыми помочь новым парням. Я понимаю, что это обычно имеет место для более крупных проектов, но все же, было бы к чему стремиться.
• Согласованность. Когда я на самом деле использую API, я не хочу шокироваться, когда вызываю метод, или обнаруживаю, что этот метод Xполностью отличается от соглашения, установленного остальной частью API.

У отличных API есть отличная документация.

• Сделай одну вещь и сделай это замечательно.
• Легко использовать, трудно злоупотреблять.
• Легко продлить.
• Хорошо задокументированы.
• Последовательный стиль.

Этот вопрос рассматривается в «Практическом проектировании API: Признания Java Framework Architect» Ярослава Тулаха из команды NetBeans.

Самый простой полезный интерфейс и хорошие соглашения об именах.