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

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

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

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

вопросы:

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

нюансы:

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

14 ответов

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

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

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

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

III. Дизайн Класса

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

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

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

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

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

36

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

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

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

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

больше, но это хорошее начало!--21-->

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++ APIs" также Trolltech

книги:

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

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

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

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

1

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

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

1

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

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

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

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

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

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

0

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

0