Метка «документация»

Mojolicious — восхитительный современный веб-фреймворк для Perl. Из недостатков я могу назвать только два: политика в отношении обратной совместимости и документация.

Содержание

1. Недостатки
2. Роутинг: внутреннее устройство
3. Роутинг: настройка
4. Параметры HTTP-запроса
5. Парсинг
6. Tips & Tricks
   1. Поддержка неблокирующих приложений в режиме CGI
   2. Как работает Mojo::UserAgent при тестировании своего приложения
   3. ojo и Mojolicious::Lite
   4. Переменные окружения

Недостатки

В официальном FAQ написано: "… we will always deprecate a feature before removing or changing it in incompatible ways between major releases … as long as you are not using anything marked experimental, untested or undocumented, you can always count on backwards compatibility …". Для начала, вторая фраза противоречит первой. Далее, вот цитата из Guides::Contributing «Features may only be changed in a major release or after being deprecated for at least 3 months.». Честно говоря, 3 месяца это и так смешной срок когда речь идёт об обратной совместимости, но похоже что даже этот срок соблюдается не всегда (поддержку «X-Forwarded-HTTPS» сделали deprecated два месяца назад, а удалили месяц назад — да, это был «major release» поэтому формально правила не нарушены, но общее отношение к обратной совместимости вполне показательно). Как много разработчиков обновляет фреймворк чаще чем раз в 3 месяца, да ещё и при этом тщательно вычитывает Changes или логи своего приложения на предмет deprecated-предупреждений? При этом, в течении последнего года было deprecated примерно 20 функций/фич. На практике, конечно, всё не так плохо, как это звучит — что-то ломается не так уж часто (лично меня за последний год коснулась только замена $app->secret() на $app->secrets()). Но факт остаётся фактом — обратную совместимость ломают, ломают часто, причём без по-настоящему веских причин: например, в случае с secret() абсолютно ничего не мешало добавить в код

sub secret { shift->secrets([shift]) }

либо просто добавить поддержку дополнительных параметров в secret() вместо добавления новой функции secrets() реализовав нужную фичу вообще не ломая совместимость.

Что касается документации, то многие считают её отличной, даже одним из серьёзных достоинств Mojolicious, но никак не недостатком. Проблема с документацией в том, что она вся сосредоточена на примерах. Это реально круто, когда ты начинаешь изучать фреймворк. Это экономит кучу времени, когда тебе нужно сделать фичу и ты быстро гуглишь пример аналогичной фичи в официальных guides. Но как только ты выходишь за рамки стандартных задач и возникает необходимость понять, как что-то устроено идеологически или архитектурно, какие конкретно параметры может принимать эта функция и что конкретно она может возвращать в разных ситуациях — выясняется, что для многих модулей Mojolicious такая документация отсутствует в принципе. И не потому, что эта информация относится к «недокументированным возможностям» — почти всё это мельком упоминается здесь и там в разных примерах, а значит считается «документированным». Нередко есть несколько способов получить доступ к определённым данным (параметры запроса, тело ответа, etc.) но не описано чем они друг от друга отличаются и в каких ситуациях правильнее пользоваться какими способами. И последнее — алфавитный порядок функций в доке, серьёзно?! Нет, я понимаю, все люди разные и кому-то наверняка это удобно, но многим всё-таки на порядок проще воспринимать документацию в которой функции сгруппированы по задачам. (Хотя в коде, особенно при чтении его через браузер, где не так удобно пользоваться поиском как в Vim, алфавитный порядок функций неожиданно оказался довольно удобным — кроме new/DESTROY/AUTOLOAD — их всё-таки лучше размещать в начале.) В результате, чтобы разобраться приходится вычитывать код (некоторые предпочитают вместо этого смотреть тесты!), что не так просто — во-первых он не является эталоном читабельности: автор любит использовать фишки перла, которые позволяют писать код компактно (и нередко такой код быстрее работает), но читабельность это ухудшает; во-вторых активное использование и наследования и обмена событиями между объектами усложняет понимание того, что и как происходит внутри 104 классов, из которых состоит Mojolicious-5.

С проблемой обратной совместимости мы мало что можем сделать (хотя, наверное, можно сделать плагин к Mojolicious, который будет её эмулировать по мере возможности). Зато вторую проблему решить не сложно — недостающую документацию можно написать самостоятельно. По мере изучения Mojolicious я планирую описывать некоторые вещи, которые, по-хорошему, должны быть в официальной документации, отсюда и название этой статьи.
Читать полностью »