Интересное выступление от разработчика из JetBrains про подход к дизайну API в проекте. Всегда придерживаюсь аналогичного же подхода, но не всегда получалось аргументировать это и «донести» до коллег (особенно при наличии дедлайнов и приличного объема старого кода «на поддержке»).
Основные мысли такие:
- хорошее API должно быть максимально простым и максимально «мощным»
- Простые вещи должны реализовываться просто: методы которые делают много лучше резать на простые вызовы которые нужны в 90% случаев и сложные
- Максимально чистое API: голые интерфейсы, или абстрактные классы там где нужно, реализацию лучше убрать из контракта чтобы упростить чтение исходников для пользователя и скрыть ненужные детали.
- хорошее API должно предотвращать «неправильный порядок» действий с ним
- Валидация
- валидация в runtime: fail fast — падаем как можно раньше и с подробной информацией о том что не так
- валидация при компиляции: type safe / generics, enums;
- минимизировать использование нестрогих типов данных: string, object и даже boolean
- Думаем о своих пользователях
- обратная совместимость должна быть всегда, если меняем API активно используем deprecated, старые методы не удаляем.
- не добавляем методы в API просто так, т.к. добавить метод легко, а изъять из использования сложно и черевато ошибками
- Запретить расширение API и по максимуму защиться в контракте классов и методов API от любых возможных действий со стороны пользователя
- все что можно — final, private
- immutable классы там где возможно
- Валидация
- хорошее API должно иметь запас по расширяемости
- достаточно абстрактный и гибкий дизайн, но не сложнее чем того требует задача
- понимание, что сразу сделать хорошо не удастся
- хорошим API важно пользоваться самому, и лучше «2 раза»
- все остальные пункты я бы добавил сюда — Просто пишите качественный код
Многие разработчики до сих пор создают документацию своих API в Word или Excel. Я использую Apiary — http://plutov.by/post/api_how_to