Разработка API в Java с подходом сверху вниз - Является ли написание Javadoc лучшей отправной точкой?

Question

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

Это лучший способ для достижения цели?Я начинаю чувствовать, что документация по API должна быть первой, которую нужно сжечь - даже до того, как будет написан первый файл .java.Это имеет несколько преимуществ:

1. Разработчик API может завершить разработку и спецификацию, а затем распределить реализацию по нескольким разработчикам.
2. Более гибкий - для изменения дизайна не требуетсякопаться в java-файлах, ища место для редактирования комментария javadoc.

Есть ли другие, кто разделяет это мнение?И если да, то как вы начнете с разработки API?

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

Answer 1

Для API (и для многих типов проблем IMO) подход «сверху вниз» для разделения и анализа проблем - это путь.

Однако (и это только мой 2c, основанный на моем личном опыте, поэтому возьмите его с крошкой соли), сосредоточиться на части Javadoc - это хорошо, , но это все еще не так достаточно и не может быть надежной отправной точкой. На самом деле, это очень ориентировано на реализацию. Так что же случилось с дизайном, моделированием и рассуждением, которое должно произойти до этого (каким бы кратким оно ни было)?

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

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

Если у вас есть это, тогда вы могли бы быть в хорошей позиции, чтобы начать выполнять некоторые предварительные Javadoc. Затем вы можете начать работать над реализацией этих интерфейсов, этих ролей. Далее следует Javadoc (в дополнение к другой документации, которая может не входить в руководства Javadoc .ie., Инструкции и т. Д.)

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

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

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

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

Google уже некоторое время загружает на YouTube свою серию видео-лекций "Google Tech Talk". Одна из них - часовая лекция под названием «Как разработать хороший API и почему это важно» . Вы можете также проверить это.

Некоторые ссылки, которые могут вам помочь:

Google Tech Talk "Beyond Test Driven Development: разработка, управляемая поведением": http://www.youtube.com/watch?v=XOkHh8zF33o

Разработка, управляемая поведением: http://behaviour -driven.org /

Сайт-компаньон к книге "Практическое API-дизайн": http://wiki.apidesign.org/wiki/Main_Page

Возвращаясь к основам - Структурированный дизайн # Сплоченность и сцепление: http://en.wikipedia.org/wiki/Structured_Design#Structured_Design

Answer 2

Первым определением интерфейса является стиль программирования по контракту для объявления предусловий, постусловий и инвариантов. Я считаю, что он хорошо сочетается с Test-Driven-Development (TDD), потому что инварианты и постусловия, которые вы пишете первыми, - это поведения, которые могут проверять ваши тесты.

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

Answer 3

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

Не существует «лучшего способа» приблизиться к разработке API, делайте все, что работает для вас.Знание предметной области также играет большую роль

Answer 4

Я большой поклонник программирования для интерфейса.Он формирует договор между разработчиками и пользователями вашего кода.Вместо того, чтобы углубляться в код, я обычно начинаю с базовой модели своей системы (диаграммы UML и т. Д., В зависимости от сложности).Это не только хорошая документация, но и визуальное разъяснение структуры системыНаличие этого делает кодирование намного проще.Этот вид проектной документации также облегчает понимание системы, когда вы возвращаетесь к ней через 6 месяцев или пытаетесь исправить ошибки :) Прототипирование также имеет свои достоинства, но будьте готовы выбросить его и начать заново.

Answer 5

Что касается меня, я всегда предпочитаю начинать с написания интерфейсов вместе с их документацией и только потом начинать с реализации.

В прошлом я использовал другой подход, который начинался с UML и затем использовалавтоматическая генерация кода.Лучший инструмент, с которым я столкнулся в этом вопросе, был Rational Rose , который не является бесплатным, но я уверен, что существует множество бесплатных плагинов и утилит.Преимущество Rational Rose перед другими дизайнерами, с которыми я столкнулся, заключалось в том, что вы можете «прикрепить» дизайн к своему коду, а затем изменить либо код, либо дизайн, а другой обновится.