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

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

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

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

вопросы:

  1. как вы определяете API как "плохой"?
  2. как вы определяете API как "хорошо"?

нюансы:

  • имена функций, которые трудно запомнить.
  • параметры функции, которые трудно понять.
  • плохо документация.
  • все настолько взаимосвязано, что если вам нужно изменить 1 строку кода, вам действительно нужно будет изменить сотни строк в других местах.
  • функции, которые уничтожают свои аргументы.
  • плохая масштабируемость из-за "скрытых" сложности.
  • от пользователя/разработчика требуется построить оболочки вокруг API, чтобы его можно было использовать.
14 60
api api-design

14 ответов:

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

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

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

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

раздел III. Дизайн Класс

  • Минимизировать Изменяемость
  • подкласс только там, где это имеет смысл
  • дизайн и документ для наследования или же запретить его

раздел IV. Метод

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

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

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

36

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

тут тоже дело вкуса. Апис может подчиняться каждому правилу в любом своде правил и все еще сосать из-за рабской приверженности различным модным идеологиям. Недавним виновником является ориентация на шаблон, в котором одноэлементные Шаблоны (немного больше, чем инициализированные глобальные переменные) и заводские Шаблоны (способ параметризации конструкции, но часто реализуемый, когда это не требуется) используются чрезмерно. В последнее время более вероятно, что инверсия управления (IoC) и связанный с ней взрыв в количестве крошечных типов интерфейса, которые добавляют избыточную концептуальную сложность в проекты.

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

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

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

12

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

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

7

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

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

6

Мне всегда нравилась эта статья в очереди под названием дизайн API имеет значение

http://queue.acm.org/detail.cfm?id=1255422

и эти столбцы также, Что касается вопросов проектирования API:

http://queue.acm.org/detail.cfm?id=1229903

6

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

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

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

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

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

3

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

2

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

статьи

  1. "небольшое руководство по дизайну API" Жасмин Бланшетт из Trolltech
  2. "определение Qt-Style C++ API" также Trolltech

книги:

  1. "эффективная Java" Джошуа блох
  2. "Практика Программирование " Керниган и Пайк
2

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

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

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

1

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

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

1

API-это плохо, когда это плохо документированы.

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

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

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

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

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

0

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

0