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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Статьи

• "Маленькое руководство по дизайну API" Жасмина Бланшетт из Тролльтеха
• "Определение QT-Style С++ API" также Trolltech

Книги:

• "Эффективная Java" Джошуа Блоха
• "Практика программирования" Кернигана и Пайка

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

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

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

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

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

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

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

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

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

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

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

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

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