Когда API сверхспроектирован? [закрытый]

Вам следует ознакомиться с Google Tech Talk How to Design A Good API and Why it Matters Джошуа Блоха ... он охватывает множество вопросов.

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

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

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

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

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

When reviewing the documentation and examples, the percentage of verbiage discussing the API in relation to itself cmpared to the percentage of verbiage discussing its application to credible use cases.

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

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

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

Two (related) questions to ask yourself come to mind immediately:

• Are there things that can be done in more than one way?
• Are there methods/properties on the API that can be expressed in terms of the rest of the API?

More difficult to answer, and not a sign of overengineering in itself, but definitely a sign the API isn't as simple as it could be yet:

• Are there other methods/properties you can introduce that would make it possible to remove more than you introduced (based on the other two questions)

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

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

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

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

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