Почему документация — ваш лучший друг
(и как создавать решения, которые продолжают работать после обновлений)
«Apps may only use public APIs and must run on the currently shipping OS.» Apple App Review Guidelines
Если вы когда-либо начинали работу с новым фреймворком и ловили себя на мысли: «Сейчас всё сам пойму, читать документацию — это слишком долго», вы точно не одиноки. У многих из нас срабатывает естественный исследовательский инстинкт: сначала попробовать, и только потом — заглядывать в инструкции. И это совершенно нормально.
Однако на этом этапе бывает легко увлечься и оказаться в ситуации, где код работает замечательно, но, возможно, опирается на неочевидные особенности системы.
Почему просто «разобраться самому» иногда бывает недостаточно?
Фреймворки, особенно закрытые, представляют собой сложные и многослойные системы. В них часто скрывается внутренняя логика и оптимизации, которые:
* не описаны в публичной документации;
* не гарантируют сохранения поведения в будущем;
* могут измениться с выходом новых версий;
* могут содержать известные разработчикам особенности, которые пока не исправлены.
Когда мы действуем интуитивно, есть риск выстроить архитектуру на случайных наблюдениях, а не на задокументированных правилах. Это может сделать код более чувствительным к обновлениям.
Документация — это не ограничение, а надежная опора
Разработчики фреймворков создают мануалы, чтобы помочь нам. Действуя в рамках документации, мы получаем:
* стабильность;
* поддержку;
* предсказуемое поведение системы.
Выходя за эти рамки, мы берем на себя дополнительные риски, и поддерживать такой код становится сложнее.
Эксперименты? Конечно. Но с пониманием границ.
Любопытство — прекрасная черта разработчика. Исследовать и пробовать новое абсолютно необходимо. Но здесь есть небольшое пожелание:
Экспериментировать комфортнее всего с опорой на best practices.
Документация — это карта, которая показывает, какие пути наиболее безопасны и поддерживаются создателями.
Взгляд со стороны: советы экспертов
Часто мы учимся у опытных коллег:
* они проводят полезные курсы,
* выступают на конференциях,
* пишут замечательные книги и блоги,
* делятся своим уникальным видением.
Многие из них делятся действительно ценным опытом. Но стоит помнить: если авторские подходы идут вразрез с официальной документацией, они могут оказаться хрупкими.
Такие «эмпирические паттерны» порой:
* работают только на конкретной версии фреймворка;
* чувствительны к обновлениям;
* могут вести себя непредсказуемо в нестандартных ситуациях.
Учиться у сообщества — здорово и полезно. Но любые, даже самые авторитетные советы, всегда стоит аккуратно сверять с официальными мануалами.
Немного о SOLID
Три идеи из принципов SOLID отлично дополняют этот подход:
* Open/Closed Principle: старайтесь расширять поведение через публичные API и по возможности не зависеть от скрытой реализации.
* Liskov Substitution Principle: полагайтесь на контракт, а не на конкретную реализацию. Иначе изменения под капотом могут привести к неожиданным сложностям.
* Dependency Inversion: стройте зависимости на абстракциях, а не на деталях.
На практике это значит, что привязка к внутренним, недокументированным деталям фреймворка делает систему хрупкой.
Опираясь на публичные интерфейсы и контракты, мы получаем:
* лучшую изоляцию кода от изменений во фреймворке;
* удобство в тестировании;
* предсказуемость и надежность архитектуры.
А если встретился баг?
Случается и так, что всё сделано по правилам, но результат не соответствует ожиданиям. Фреймворки развиваются и не всегда идеальны. В таких случаях:
* Соберите минимальный пример, на котором воспроизводится проблема.
* Убедитесь, что используются только задокументированные API.
* Отправьте баг-репорт — команда разработчиков наверняка оценит ваш труд и постарается помочь.
Если же пример опирается на обходные пути, разработчикам будет гораздо сложнее оказать поддержку.
Как выжать максимум из фреймворка
* Обращайтесь к документации.
* Придерживайтесь гайдов и рекомендаций авторов.
* Экспериментируйте в пределах описанного функционала.
* Сверяйте советы из сети с официальными источниками.
* Локализуйте баги с уважением к контрактам фреймворка.
Заключение
Фреймворки — это мощные инструменты со своими правилами игры. Забывая о них, мы рискуем сделать наш код излишне уязвимым. А ведь всем нам хочется, чтобы созданные продукты жили долго и не требовали срочных исправлений после каждого минорного апдейта.
Мануалы и документация — это отличная поддержка, которая помогает создавать по-настоящему надежные решения.
Источники
https://developer.apple.com/app-store/review/guidelines/
https://en.wikipedia.org/wiki/SOLID
https://en.wikipedia.org/wiki/API
https://en.wikipedia.org/wiki/RTFM