Разработка API в Java с нисходящим подходом. Является ли написание Javadoc лучшей отправной точкой?
Всякий раз, когда мне нужно спроектировать API на Java, я обычно начинаю с того, что открываю свою среду IDE и создаю пакеты, классы и интерфейсы. Реализации метода все фиктивные, но Javadocs детализированы.
Это лучший способ идти о вещах? Я начинаю ощущать, что документация по API должна быть первой, которая будет производиться - даже до того, как будет написан первый файл.java. Это имеет несколько преимуществ:
- Разработчик API может завершить проектирование и спецификацию, а затем разделить реализацию между несколькими разработчиками.
- Более гибкий - изменение в дизайне не требует, чтобы он просматривался среди java-файлов в поисках места для редактирования комментария javadoc.
Есть ли другие, кто разделяет это мнение? И если да, то как вы начнете с разработки API?
Кроме того, есть ли инструменты, которые могут помочь? Возможно, даже какой-нибудь инструмент, основанный на аннотациях, который генерирует документацию, а затем скелетный источник (вроде генераторов моделей для кода)? Я сталкивался с инструментами Eclipse PDE API - но это специфично для проектов плагинов Eclipse. Я не нашел ничего более общего.
5 ответов
Для 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 "За пределами управляемой тестированием разработки: разработка, основанная на поведении": 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
Первым определением интерфейса является стиль программирования по контракту для объявления предусловий, постусловий и инвариантов. Я считаю, что он хорошо сочетается с Test-Driven-Development (TDD), потому что инварианты и постусловия, которые вы пишете первыми, - это поведения, которые могут проверять ваши тесты.
Кроме того, кажется, что разработка TDD, основанная на поведенческом развитии, возникла из-за программистов, которые обычно не думали об интерфейсе в первую очередь.
Я большой поклонник программирования для интерфейса. Он формирует договор между разработчиками и пользователями вашего кода. Вместо того, чтобы углубляться в код, я обычно начинаю с базовой модели своей системы (диаграммы UML и т. Д., В зависимости от сложности). Это не только хорошая документация, но и визуальное разъяснение структуры системы. Наличие этого делает кодирование намного проще. Этот вид проектной документации также облегчает понимание системы, когда вы возвращаетесь к ней через 6 месяцев или пытаетесь исправить ошибки:) Прототипирование также имеет свои достоинства, но будьте готовы выбросить его и начать заново.
Что касается меня, я всегда предпочитаю начинать с написания интерфейсов вместе с их документацией и только потом начинать с реализации.
В прошлом я использовал другой подход, который начинался с UML, а затем с использованием автоматической генерации кода. Лучшим инструментом, с которым я столкнулся, был Rational Rose, который не является бесплатным, но я уверен, что есть много бесплатных плагинов и утилит. Преимущество Rational Rose перед другими дизайнерами, с которыми я столкнулся, заключалось в том, что вы можете "прикрепить" дизайн к своему коду, а затем изменить либо код, либо дизайн, а другой обновится.
Я прыгаю прямо с кодировки с прототипом. Любые необходимые интерфейсы скоро появятся у вас, и вы сможете превратить ваш прототип в конечный продукт. Получите обратную связь от тех, кто собирается использовать ваш API, если вы можете.
Не существует "лучшего" подхода к разработке API, делайте все, что работает для вас. Знание предметной области также играет большую роль