Что хорошего в API, что делает их великолепными? Я думаю, что придерживаться мантры «делай одно и делай хорошо» - это хороший знак, а быть хорошим отображением проблемной области важно, но что общего у хороших API?
api-design
dan_waterworth
источник
источник
Ответы:
Вы должны быть осторожны, чтобы не добавлять новый словарь только ради вашего API. Мои любимые API объясняют мне слова, которые я уже понимаю. В том же духе:
Не добавляйте слишком много абстракций поверх того, что вы строите. Будь проще.
Я уже должен думать о полдюжине слоев абстракции. Не заставляйте меня думать о дополнительных слоях. Не давайте мне слишком много новых вещей, чтобы учиться, которые не добавят ценность моей конечной цели. Например, избегайте использования своего собственного специального класса файлов, который работает иначе, чем тип файла языка, потому что вы думаете, что ваш путь лучше, чем общепринятый способ. Придерживайтесь общепринятого способа, по крайней мере, в ваших интерфейсах, к лучшему или к худшему.
Придерживаться конкретных идей
Например, не пытайтесь скрыть тот факт, что «модельная» часть вашей инфраструктуры MVC является внешним интерфейсом для базы данных. Воспользуйтесь хорошо известным словарем, окружающим «базы данных». Я знаю, что такое внешние ключи. Я знаю, что такое строки и столбцы. Поговори со мной в этих условиях.
Не абстрагируйте необходимые знания
Похоже на работу с конкретными идеями. Не скрывайте, что мы имеем дело с файлами, базами данных или строками в базах данных. Я знаю эти вещи. Если я имею дело с контейнером, таким как List, есть хороший шанс, что мне нужно знать алгоритмическую сложность обычных операций. Вы можете упростить это, просто сказав мне «связанный список» или «массив». Огромный набор идей внезапно будет связан с тем, что вы делаете, и все это внезапно обретет смысл. Не создавайте свой собственный набор идей, которые я должен выучить, когда я уже приду с богатым и полезным набором терминологии для применения к проблеме.
Сократить количество терминов, которые мне нужны в моем словаре
Если я использую ваш API для открытия файла изображения любого типа, мне не нужно слишком много думать о pngs vs gifs vs jpgs. Ты сделаешь это для меня. Это ваша основная компетенция, а не моя. У меня есть смутное понимание, что у тебя есть немного магии, чтобы сделать это для меня.
источник
Полезный API имеет следующее:
X
полностью отличается от соглашения, установленного остальной частью API.источник
У отличных API есть отличная документация.
источник
источник
Этот вопрос рассматривается в «Практическом проектировании API: Признания Java Framework Architect» Ярослава Тулаха из команды NetBeans.
источник
Самый простой полезный интерфейс и хорошие соглашения об именах.
источник