Занятие №4 в рамках Курсов программирования Ruby on Rails.
Группа курсов «ВКонтакте»: http://vk.com/ruby_school
Организатор — Агентство интернет-маркетинга Мэйк makeagency.ru. Курсы проводятся на базе Кузбасского государственного технического университета, кафедры «Информационные и автоматизированные производственные системы».
noBackend, или Как выжить в эпоху толстеющих клиентов / Самохвалов НиколайOntico
Набирает обороты мода на парадигму noBackend (см., например, http://nobackend.org/). Название не стоит понимать буквально: backend никуда не делся, просто фокус разработки — особенно на начальном этапе развития нового проекта — сильно смещается в сторону «клиентской части». Это очень понятно и закономерно в эпоху Mobile First и React Ecosystem с её новомодными GraphQL и React Native.
Появляется большой соблазн взять что-то понятное для хранения данных и уже «обвязанное» REST API, максимально отказаться от PHP/Python/Ruby/Java/etc, писать 80% кода «на стороне клиента», минимально заботясь о возне «на стороне сервера». У некоторых возникает и настоящая эйфория — чувство приятное, но очень опасное (прежде всего, если в команде нет сильного backend-опыта).
Этот доклад — компиляция опыта ряда проектов, написанных на React, React Native и Swift и переходящих на парадигму (или же сразу стартанувших с неё) noBackend за счёт PostgreSQL+PostgREST.
Мы обсудим важные вопросы, которые обязан задавать себе каждый, выбравший noBackend-подход (и не обязательно на связке Postgres+PostgREST): безопасность (аутентификация/авторизация; ограничение чтения и — особенно! — модификации «чужих» данных), производительность (нетривиальные запросы а-ля «свежий контент от тех, на кого я подписан»; компромисс между сетевой сложностью и CPU; защита от «домашнего» ddos — ситуации, когда свои же, родные «фронтендеры» кладут «бэкэнд»), масштабируемость и асинхронная обработка задач.
Задача-минимум (для всех): у каждого слушателя остаётся список must-check-вопросов для работы с noBackend-подходом.
Задача-максимум (для тех, кто с Postgres-опытом): разворачивание безопасного, высокопроизводительного и годного для быстрого развития REST API — сегодня же, в день док
Занятие №4 в рамках Курсов программирования Ruby on Rails.
Группа курсов «ВКонтакте»: http://vk.com/ruby_school
Организатор — Агентство интернет-маркетинга Мэйк makeagency.ru. Курсы проводятся на базе Кузбасского государственного технического университета, кафедры «Информационные и автоматизированные производственные системы».
noBackend, или Как выжить в эпоху толстеющих клиентов / Самохвалов НиколайOntico
Набирает обороты мода на парадигму noBackend (см., например, http://nobackend.org/). Название не стоит понимать буквально: backend никуда не делся, просто фокус разработки — особенно на начальном этапе развития нового проекта — сильно смещается в сторону «клиентской части». Это очень понятно и закономерно в эпоху Mobile First и React Ecosystem с её новомодными GraphQL и React Native.
Появляется большой соблазн взять что-то понятное для хранения данных и уже «обвязанное» REST API, максимально отказаться от PHP/Python/Ruby/Java/etc, писать 80% кода «на стороне клиента», минимально заботясь о возне «на стороне сервера». У некоторых возникает и настоящая эйфория — чувство приятное, но очень опасное (прежде всего, если в команде нет сильного backend-опыта).
Этот доклад — компиляция опыта ряда проектов, написанных на React, React Native и Swift и переходящих на парадигму (или же сразу стартанувших с неё) noBackend за счёт PostgreSQL+PostgREST.
Мы обсудим важные вопросы, которые обязан задавать себе каждый, выбравший noBackend-подход (и не обязательно на связке Postgres+PostgREST): безопасность (аутентификация/авторизация; ограничение чтения и — особенно! — модификации «чужих» данных), производительность (нетривиальные запросы а-ля «свежий контент от тех, на кого я подписан»; компромисс между сетевой сложностью и CPU; защита от «домашнего» ddos — ситуации, когда свои же, родные «фронтендеры» кладут «бэкэнд»), масштабируемость и асинхронная обработка задач.
Задача-минимум (для всех): у каждого слушателя остаётся список must-check-вопросов для работы с noBackend-подходом.
Задача-максимум (для тех, кто с Postgres-опытом): разворачивание безопасного, высокопроизводительного и годного для быстрого развития REST API — сегодня же, в день док
3. Какие компонентыпакета отвечают за документацию
• Над функциями и другими объектами, которые вам надо задокументировать вы
прописываете специальные roxygen комментарии
• После генерации все файлы документации хранятся в каталоге man/.
4. Рабочий процесс
1. Добавляете roxygen2 комментарии над объектами, к которым хотите сгенерировать
документацию (Ctrl+Shift+Alt+R когда курсор находится внутри кода функции или кода
генерирующего объект)
2. Запускаете devtools::document() (Ctrl/Cmd + Shift + D), чтобы преобразовать комментарии
roxygen2 в .Rd файлы.
3. Запускаете предварительный просмотрт сгенерированной документации с помощью
?function_name.
4. Исправляете ошибки, повторяете процесс до тех пор, пока не получите нужный
результат.
5. Структура roxygen комментариев
• Комментарии roxygen2 начинаются с #’
• Все комментарии roxygen2, предшествующие функции называются блоком
• Блоки разбиваются на теги , которые выглядят как @tagName tagValue
• По умолчанию каждый блок генерирует один топик документации , т.е. один .Rd файл в
man/ каталоге.
6. Особенности разметки
• Используйте апострофы для выделения блока текста как кода: #' I like `thisfunction()`,
because it's great.
• Для добавление ссылки на документацию к другой функции вашего или стороннего пакета
используйте квадратные скобки:
#' It's obvious that `thisfunction()` is better than [otherpkg::otherfunction()]
#' or even our own [olderfunction()].
• Ссылайтесь на виньетки с помощью кода: vignette("rd-formatting", package = "roxygen2")
• Маркированные списки прописываются так же, как и в обычном markdown:
#' Best features of `thisfunction()`:
#' * Smells nice
#' * Has good vibes
7. Разделыдокументации
• Заголовок (@title) – Обычно задаётся позиционно в первой строке roxygen комментария
• Описание (@description) – Более подробное описание, что делает ваша функция, можно
задать позиционно, второй строкой roxygen комментария
• Детали (@details) – Тут описывают важные детали использования вашей функций, можно
задать позиционно третей строкой комментария
• Аргументы функции (@param) – Описание каждого аргумента функции
• Возвращаемое значение (@return) – Какой объект возвращает ваша функция
• Примеры (@examples) – Примеры использования вашей функции
8. Title, description и details
• Первые 3 тега roxygen можно использовать позиционно, без указания их названий:
• Title – заголовок должен быть написан в регистре заголовков, не заканчиваться точкой и после него
должна идти пустая строка.
• Description – более подробное описание того, что делает функция, как правило занимает один абзац.
Если ваше описание требует более чем один абзац вам придётся явно использовать тег @description.
• Details – описание деталей работы вашей функции, в осном этот блок не используется в
документации. Хорошей практикой является создание пользовательских разделов подробностей с
помощью тега @section.
9. Аргументы
• Для документирования аргументов функции используйте тег @param
• Если использование нескольких аргументов тесно связано между собой можете
объединить их через запятую, без указания пробела: #' @param x,y A pair of character
vectors.
• Тег @inheritParams позволяет наследовать описание аргументов из других функций вашего
или даже стороннего пакета. При этом будут унаследованы только те аргументы, которые
присутвуют в новой функции, и которые в ней отдельно не были задокументированы.
10. Возвращаемое значение
• За возвращаемое значение отвечает тег @returns
• Для возвращаемого значения вам необходимо описать класс, тип и размер возвращаемого
функцией значения.
11. Примеры
• Примеры описываются с использованием тега @examples
• Все прописанные примеры должны выполняться без ошибок, поскольку они регулярно
проверяются:
• В интерактивном режиме с помощью команды example()
• Во время работы R CMD check на вашем компьютере
• Во время проверки R CMD check на CRAN.
• Когда генерируется веб-сайт вашего пакета с помощью pkgdown
• При использовании нестабильных ресурсов в ваших примерах, например веб-сайтах
используйте тег @examplesIf, который позволяет пропускать такие примеры, так же можно
завернуть ваши примеры в dontrun{}, для избегания запуска примеров, которые заведомо
заканчиваются ошибками.
12. Повторное использование документации
• При необходимости объединить документацию нескольких функций в один файл
документации используйте тег @rdname, и передайте в него название функции, в которой
подробно описана документация всех функций.
• Теги отвечающие за наследование частей документации:
• @inherit source_function - унаследует все поддерживаемые компоненты от source_function().
• @inheritSection source_function Section title - унаследует один раздел с заголовком «Section title» от
source_function().
• @inheritDotParams - автоматически генерирует документацию по параметрам для ... общего случая,
когда вы переходите ... к другой функции.
13. Раздел справки по пакету
• Используйте функцию usethis::use_package_doc() для генерации файла R/{pkgname}-
package.R, который содердит документацию уровня пакета.
• Так же это хорошее место для хранения импорта, т.е. тегов @import и @importFrom.