Разработка API в Java-проекте

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

Основные мысли такие:

• хорошее API должно быть максимально простым и максимально «мощным»
  1. Простые вещи должны реализовываться просто: методы которые делают много лучше резать на простые вызовы которые нужны в 90% случаев и сложные
  2. Максимально чистое API: голые интерфейсы, или абстрактные классы там где нужно, реализацию лучше убрать из контракта чтобы упростить чтение исходников для пользователя и скрыть ненужные детали.
• хорошее API должно предотвращать «неправильный порядок» действий с ним
  1. Валидация
     • валидация в runtime: fail fast — падаем как можно раньше и с подробной информацией о том что не так
     • валидация при компиляции: type safe / generics, enums;
     • минимизировать использование нестрогих типов данных: string, object и даже boolean
  2. Думаем о своих пользователях
     • обратная совместимость должна быть всегда, если меняем API активно используем deprecated, старые методы не удаляем.
     • не добавляем методы в API просто так, т.к. добавить метод легко, а изъять из использования сложно и черевато ошибками
  3. Запретить расширение API и по максимуму защиться в контракте классов и методов API от любых возможных действий со стороны пользователя
     • все что можно — final, private
     • immutable классы там где возможно
• хорошее API должно иметь запас по расширяемости
  1. достаточно абстрактный и гибкий дизайн, но не сложнее чем того требует задача
  2. понимание, что сразу сделать хорошо не удастся
  3. хорошим API важно пользоваться самому, и лучше «2 раза»
• все остальные пункты я бы добавил сюда — Просто пишите качественный код