Когда API перенастроен?

Ответ 1

"Каковы некоторые предупреждающие знаки с точки зрения разработчика, что ваш API может быть перенастроен?"

Нет прецедентов.

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

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

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

Ответ 2

Вы должны проверить Google Tech Talk Как создать хороший API и почему это имеет значение Джошуа Блоха... он много охватывает из этого материала.

Ответ 3

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

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

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

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

Ответ 4

когда трассировка стека для общего вызова api требует прокрутки экрана, чтобы увидеть всю вещь.

Ответ 5

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

Ответ 6

Как сказал С.Лотт, прецеденты. Они будут определять, что именно ваш API должен быть направлен на выполнение. Если вы создадите свой API для выполнения очень четкой, конкретной цели - функционально согласованной - вы, скорее всего, закончите с API или компонентом в вашем API, который является простым в использовании и понимании.

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

Я бы связался с этими концепциями пользовательского интерфейса, но я новый пользователь, поэтому они не позволят мне размещать более 1 гиперссылки. Хороший пример: StackOverflow, сообщите нам, прежде чем публиковать;).

Ответ 7

Два (связанных) вопроса, чтобы спросить себя, сразу приходят в голову:

• Есть ли что-то, что можно сделать более чем одним способом?
• Существуют ли методы/свойства API, которые могут быть выражены в терминах остальной части API?

Сложнее ответить, а не признак overengineering в себе, но определенно признак API не так прост, как он может быть еще:

• Есть ли другие методы/свойства, которые вы можете ввести, что позволило бы удалить больше, чем вы ввели (по двум другим вопросам).

Ответ 8

Когда это так умно, что никто не может его понять.

Ответ 9

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

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

Ответ 10

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

Ответ 11

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