Как вы определяете хороший или плохой API?

Справочная информация:

Я беру класс в своем университете под названием "Software Constraints". На первых лекциях мы изучали, как создавать хорошие API.

Хорошим примером того, что мы получили очень плохую функцию API, является сокет public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); в С#. Функция получает 3 списка сокетов и уничтожает их, заставляя пользователя клонировать все сокеты перед подачей их в Select(). Он также имеет тайм-аут (в микросекундах), который является int, который устанавливает максимальное время ожидания сервером сокета. Пределы этого составляют +/- 35 минут (потому что это int).

Вопросы:

  • Как вы определяете API как 'Плохо'?
  • Как вы определяете API как "хороший"?

Вопросы для рассмотрения:

  • Названия функций, которые трудно запомнить.
  • Параметры функции, которые трудно понять.
  • Плохая документация.
  • Все настолько взаимосвязано, что если вам нужно изменить 1 строку кода, вам действительно нужно будет изменить сотни строк в других местах.
  • Функции, которые уничтожают их аргументы.
  • Плохая масштабируемость из-за "скрытой" сложности.
  • Требуется, чтобы пользователь /dev создавал обертки вокруг API, чтобы его можно было использовать.

ОТВЕТЫ

Ответ 1

В дизайне API я всегда считал, что это ключевое слово очень полезно:
Как создать хороший API и почему это имеет значение - Джошуа Блох

Здесь выдержка, я бы рекомендовал прочитать все это/посмотреть видео.

II. Общие принципы

  • API должен делать одно дело и делать это хорошо
  • API должен быть как можно меньше, но не меньше
  • Реализация не должна влиять на API
  • Минимизировать доступность всего
  • Имена Matter-API - это маленький язык
  • Вопросы документации
  • Документ религиозно
  • Рассмотрим последствия производительности решений API для проектирования
  • Эффекты решений API по разработке производительности являются реальными и постоянными.
  • API должен мирно сосуществовать с платформой.

III. Дизайн классов

  • Свернуть Mutability
  • Подкласс только там, где он имеет смысл
  • Дизайн и документ для наследования или других запретов.

IV. Дизайн метода

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

Ответ 2

Вам не обязательно читать документацию, чтобы использовать ее правильно.

Знак удивительного API.

Ответ 3

Многие стандарты кодирования и более длинные документы и даже книги (Framework Design Guidelines ) были написаны на эту тему, но многое из этого помогает лишь на довольно низком уровне.

Есть также вопрос вкуса. API могут подчиняться каждому правилу в любом сводке правил и все еще сосать из-за рабской приверженности различным идеологиям в моде. Недавним виновником является ориентация шаблона, в котором используются Singleton Patterns (немного больше, чем инициализированные глобальные переменные) и Factory Шаблоны (способ параметризации построения, но часто реализуемый, когда они не нужны). В последнее время более вероятно, что Inversion of Control (IoC) и связанный с ним взрыв в количестве крошечных типов интерфейсов, что добавляет излишнюю концептуальную сложность в конструкции.

Лучшие репетиторы по вкусу - это подражание (чтение много кода и API, выяснение того, что работает и не работает), опыт (совершение ошибок и обучение от него) и мышление (не просто делать то, что модно для его Сайте, подумайте, прежде чем действовать).

Ответ 4

  • Полезно - он устраняет необходимость, которая еще не удовлетворена (или улучшена на существующих).
  • Легко объяснить - основное понимание того, что он делает, должно быть простым в понимании.
  • Следует некоторой объектной модели какого-либо проблемного домена или реального мира. Он использует конструкции, которые имеют смысл
  • Правильное использование синхронных и асинхронных вызовов. (не блокируйте вещи, требующие времени)
  • Хорошее поведение по умолчанию - по возможности позволяет расширяемость и настройку, но предоставляет значения по умолчанию для всего, что необходимо для простых случаев.
  • Примеры использования и рабочие примеры приложений. Это, вероятно, самое важное.
  • Отличная документация
  • Ешьте свою собачью пищу (если применимо)
  • Держите его маленьким или сегментируйте так, чтобы он не был одним огромным загрязненным пространством. Храните функциональные наборы отличными и изолированными с небольшим количеством зависимостей.

Есть больше, но это хорошее начало

Ответ 5

Хороший API позволяет клиенту делать почти все, что им нужно, но не требует от них много бессмысленной занятой работы. Примерами "бессмысленной занятой работы" будут инициализация полей структуры данных, вызов нескольких подпрограмм в последовательности, которая никогда не меняется без реального пользовательского кода между ними и т.д.

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

Ответ 6

Хороший API имеет семантическую модель, близкую к тому, что она описывает.

Например, API для создания и обработки таблиц Excel будет иметь такие классы, как Workbook, Sheet и Cell, с такими методами, как Cell.SetValue(text) и Workbook.listSheets().

Ответ 8

Плохой API - это тот, который не используется целевой аудиторией.

Хороший API - это тот, который используется целевой аудиторией для целей, для которых он был разработан.

Отличный API - это тот, который используется как своей целевой аудиторией, так и по назначению, и непреднамеренная аудитория по причинам, непредвиденным ее дизайнерами.

Если Amazon публикует свой API как SOAP и REST, а версия REST выигрывает, это не значит, что базовый API SOAP был плохим.

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

Ответ 9

Хороший API - это тот, который упрощает простые вещи (минимальный шаблон и кривая обучения, чтобы делать самые распространенные вещи) и сложные вещи (максимальная гибкость, как можно меньше предположений). Средним API является тот, который делает один из них хорошо (либо безумно простой, но только если вы пытаетесь сделать действительно базовые вещи или безумно мощные, но с действительно крутой кривой обучения и т.д.). Ужасный API - это тот, который не делает ничего хорошего.

Ответ 10

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

Статьи

Книги:

Ответ 11

Я думаю, что хороший API должен позволять настраивать IO и управления памятью, если это применимо.

Типичный пример: у вас есть собственный формат сжатого архива для данных на диске, а сторонняя библиотека с плохой api хочет получить доступ к данным на диске и ожидает путь к файлу, где он может загружать свои данные.

У этой ссылки есть некоторые хорошие моменты: http://gamearchitect.net/2008/09/19/good-middleware/

Ответ 12

Если API создает сообщение об ошибке, убедитесь, что сообщение и диагностика помогают разработчику решить, в чем проблема.

Мое ожидание заключается в том, что вызывающий API API правильно вводит входные данные. Разработчик является потребителем любых сообщений об ошибках, создаваемых API (а не конечным пользователем), а сообщения, направленные на разработчика, помогают разработчику отлаживать свою вызывающую программу.

Ответ 13

API плохо, если он плохо документирован.

API хорош, когда он хорошо документирован и следует стандарту кодирования.

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

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

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

Я немного написал о структуре кодирования здесь

Ответ 14

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