sdj_raising_your_code_to_professional_standards
1.0.0
Это грубая версия статьи, опубликованной в sdjournal , по адресу https://sdjournal.org/raising-code-professional standards. Моя статья находится в бесплатном разделе, и вы можете зарегистрироваться с учетной записью GitHub.
Вы хотите быть хорошим. Вы хотите научиться писать пакет, который следует за всеми экспертными руководящими принципами. Вы открыты для того, чтобы быть исправленным любым профессиональным инструментом и учитесь на нем. Вы хотите программировать как профессионалы. Вы хотите создать пакет, которым гордитесь.
Тогда вы должны прочитать эту статью.
Вы научитесь добавлять автоматическое тестирование для стандарта кодирования, покрытия кода и хороших практик. Все это запускается путем GIT, проталкивающего команду, которая загружает код вашего пакета на свой GitHub.
Мы используем пример пакета в качестве тестового примера.
В конце концов, у вас будет сценарий, который заставляет вас работать как профессионал.
Предполагается, что вы знаете, как
Если вы еще не можете прочитать функцию R, я рекомендую прочитать [Matloff, 2011] или использовать пакет «вихрь».
Если вы не можете написать пакет, использовать Testthat или знать GitHub, я рекомендую прочитать [Hadley, 2015].
Мне нравится преподавать программированию после самых высоких стандартов отрасли. Мои ученики, в возрасте 7-77 лет, сталкиваются с цитатами советов из литературы, особенно из «Прагматического программиста» Эндрю Ханта и Дэвида Томаса. Что касается R, мне нравится цитировать все советы от Хэдли Уикхэма.
Следуя хорошей практике экспертов сэкономит время в разработке кода.
Настройка этой статьи следует некоторым из этих хороших практик. Практика представляет собой рациональный стандарт кодирования, имеет высокое покрытие кода (весь код тестируется) и используйте r в прагматическом способе.
В этой статье я покажу, как мне помогать эксперты.
Во -первых, я представлю пакет «prde» («Professional R Development»). Этот пакет служит тестовым примером для того, чтобы показать, как его недостатки выявляются в результате настройки этой статьи. Таким образом, упаковка ошибочна, но проходит все тесты CRAN. «PRDR» размещен на GitHub.
Затем я показываю, как настроить учетные записи для двух веб -сайтов, которые будут беспрепятственно взаимодействовать с учетной записью GitHub. Это Travis CI, для настройки автоматического тестирования (подробнее об этом позже) и Codecov, который отслеживает покрытие кода пакета (подробнее об этом позже).
На всем активированном веб -сайтах файл загружается на GitHub пакета, который будет вызывать ответы на веб -сайте Travis CI и Codecov. Я обсуждаю эти ответы один за другим.
Тестовый пример представляет собой пакет под названием «prde», который следует за структурой, описанной в [Wickham, 2015]. Пакет размещен на GitHub:
Рисунок 1. Гитуб пакета 'prde'
В рамках пакета «PRDE» находится функция, называемая DO_MAGIC , как это:
#' Multiplies all values by two,
#' except 42, which stays 42
#' @param x input, must be numeric
#' @return magicified output
#' @export
do_magic <- function(x)
{
if (!is.numeric(x)) {
stop("x must be numeric");
}
out = x * 2;
out = replace(out, out == 84, 42);
out;
}
Листинг 1. Функция 'do_magic'
Функция DO_MAGIC хранится в файле в обычном месте, которое является R/DO_MAGIC.R . Он задокументируется с использованием пакета "Roxygen2". Функция проверяет правильный ввод и быстро не работает, если не может обработать их.
Пакет имеет некоторые тесты, используя «testthat», как показано ниже:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
Листинг 2. Тесты do_magic
Этот тест хранится в файле в обычном месте, который является тестами/testthat/test-do_magic.r . Тесты все проходят. Ошибки не обнаружены при проверке пакета для построения в RSTUDIO или с использованием DevTools :: Check () . Это означает, что пакет может быть отправлен в CRAN без каких -либо проблем (за исключением того, чтобы убедить, что пакет актуален)!
Непрерывная интеграция означает, что эффект изменения кода после загрузки его в GitHub отображается автоматически через короткое время. Другими словами: если пакет больше не может построить в представленном недостатках (например, тестирование, которое сейчас терпит неудачу), он будет замечен рано. Или, если кто -то еще сломает его, команда заметит рано. Кроме того, когда кто -то подает запрос на привлечение, можно увидеть, сломает ли он построение пакета, прежде чем принять его.
Есть много других служб непрерывной интеграции, которые работают так же хорошо, как Дженкинс, Codeship, Circleci и Wercker. Я только что случайно изучил Трэвис Си первым.
Рисунок 2. Логотип Travis CI
Первый шаг нашей настройки - активировать Travis CI.
Travis CI - это служба непрерывной интеграции (следовательно, «CI» в имени), которая может свободно использовать при разработке программного обеспечения для флосса и хорошо работает с GitHub.
Давайте сначала активируем Travis CI, потому что только после активации он начнет работать при загрузке в GitHub.
Чтобы сделать это: перейдите на веб-сайт Travis CI, www.travis-ci.org и войдите в учетную запись GitHub. Трэвис запрашивает авторизацию для некоторой информации GitHub, такой как имя пользователя и электронная почта. После авторизации Трэвис CI показывает все хранилища GitHub пользователя и статус их активации:
Рисунок 3. Обзор GitHubs, проверенные Travis CI
На этом рисунке показан пользователь, который имеет как минимум три репозиторию GitHub, из которых один не активирован (серый крест), а два - (зеленая проверка).
Найдите GitHub пакета R и активируйте его.
Покрытие кода - это процент строк кода, охватываемых тестами. Если строка не проверена, обнаруживается либо мертвый код (который может быть удален), либо должен быть написан тест, который использует этот код. Покрытие кода коррелирует с качеством кода [Del Frate et al., 1995].
Существуют и другие услуги, которые отслеживают покрытие кода, такие как кодовый климат, кодалеза, комбинезоны, количественный код и многое другое. Просто оказалось, что пакет, который мы используем ('lintr'), использует Codecov.
Рисунок 4. Логотип Codecov
Второй шаг - активировать Codecov.
Codecov-это веб-сайт, который показывает покрытие кода GitHub репозитория в удобной форме. Codecov отслеживает покрытие кода проекта в течение времени. Если есть несколько ветвей GIT, покрытие кода отображается отдельно для каждой ветви.
Нам нужно активировать Codecov сейчас, потому что
Codecov будет получать и отображать только покрытие кода зарегистрированных пользователей.
Чтобы активировать Codecov, перейдите на его веб -сайт https://codecov.io и войдите в учетную запись Github. Он запросит авторизацию для некоторой информации GitHub, такой как имя пользователя и электронная почта.
После авторизации Codecov отображает покрытие кода всех Githubs пользователя. Для нового пользователя этот экран будет в основном пустым, так как охват кода еще не измеряется. Для пользователя, у которого измерено покрытие кода нескольких репозиториев GitHub, экран Codecov будет выглядеть следующим образом:
Рисунок 5: Пример обзор GitHubs, проверенный Codecov
На этом рисунке можно увидеть использование, в котором есть как минимум три репозиторию GitHub, которые проверяют покрытие кода.
Третий шаг состоит в том, чтобы инструктировать Трэвис CI, что делать, когда новый код загружается на активированный GitHub.
Трэвису проинструктируется, что делать, используя сценарий сборки, который представляет собой открытый файл с именем .travis.yml . Имя файла начинается с точки, что делает его скрытым файлом в системах UNIX. Расширение «.yml» - это аббревиатура «еще одного языка разметки». Трэвис CI проинструктируется на языке команд Bash.
В корневой папке проекта создайте файл с именем .travis.yml и поместите в него следующий текст:
language: r
cache: packages
r_github_packages:
- jimhester/lintr
- jimhester/covr
- MangoTheCat/goodpractice
after_success:
- Rscript -e "lintr::lint_package()"
- Rscript -e "covr::codecov()"
- Rscript -e "goodpractice::gp()"
Листинг 3. Сценарий Трэвиса CI
Это простой и простой сценарий .travis.yml . В первой строке говорится, что используемый здесь язык программирования R. Вторая строка говорит Трэвису CI, чтобы держать установленные пакеты в кэше, чтобы предотвратить ненужные переустановки этих пакетов. В разделе «r_github_packages» инструктируется Трэвис CI установить эти пакеты с GitHub. Раздел «After_success» запускается после того, как пакет проходит Devtools :: check () . В этом разделе он будет запускать чеки из пакетов «Lintr», «Covr» и «GoodPractice». Подробнее об этих пакетах позже.
После создания этого файла .travis.yml загрузите его в GitHub.
После загрузки .travis.yml на GitHub, он сразу же будет видна на GitHub:
Рисунок 6. GitHub 'prde после добавления сценария сборки Travis CI
Этот толчок к GitHub запускает Travis CI, и он сразу же начнет выполнять свою работу.
Трэвису CI требуется некоторое время, чтобы настроить виртуальную машину. Каждый раз, когда производится загрузка на GitHub, создается виртуальная машина, чтобы обеспечить воспроизводимую среду сборки и тестирования.
Чтобы увидеть, как Трэвис Си делает свою работу, вернитесь на веб-сайт Travis CI, https://travis-ci.org . Примерно через одну минуту прогресс Трэвиса Си становится видимым. Трэвис CI сначала устанавливает все пакеты и их зависимости. Сценарий .travis.yml кэширует все пакеты, что делает вторую сборку быстрее.
Вот заголовок пакета «prde» его первой сборки:
Рисунок 7. Заголовок пакета «PRDE» его первой сборки
Мы уже знаем, что пакет пройдет этот чек, так как он был проверен уже в RStudio. Если сборка не пройдет, тот же вывод будет показан, как указано Devtools :: check () и ничего более. Если сборка проходит, внизу будет какая -то новая информация:
Рисунок 8. Внизу пакета «prde» его первая сборка
Нажатие на треугольники слева раскрывает некоторую дополнительную информацию.
Во -первых, мы расширим отзывы из пакета «Lintr» (Джим Хестер). Это показывает:
Рисунок 9. Отзывы, данный пакетом «Lintr»
«Lintr»-это пакет, чтобы проверить, следует ли пакет его стиль кодирования, следует за хорошо складываемыми стандартами, как и Wickham (2014) и Wickham (2015).
Рисунок 10. Джим Хестер
Вывод «Lintr» не только показан на веб -сайте Travis CI. Кроме того, мой хороший друг Линтр-Бот прокомментирует коммит на GitHub, с точно такими же сообщениями:
Рисунок 11. Комментарии Lintr-Bot на коммите, как показано на GitHub
Линтр-бот всегда прав. При необходимости можно сделать «Lintr», чтобы обеспечить другие стандарты кодирования.
Рисунок 12. Логотип Mangothecat
Переходя от слов мудрости Lintr-Bots, мы расширим обратную связь из пакета «GoodPractice» (от Mangothecat). Это показывает:
Рисунок 13. Обратная связь, данная пакетом «GoodPractice»
«GoodPractice» расширяет «Lintr», добавляя хорошие практики. Например, он может предположить не использовать определенную функцию, а вместо этого использовать лучшую альтернативу.
Существует третий треугольник, который может быть расширен, предоставляя информацию о вызове в пакет «COVR», в журнале Travis Build. Просмотр этой информации здесь не полезно, так как она отображается в грубой форме. Вместо этого вернитесь на веб -сайт Codecov, https://codecov.io, чтобы просмотреть покрытие кода более красивым образом:
Рисунок 14. Обратная связь, данная пакетом «COVR», как показано CodeCov
Покрытие кода показывает, что автор «PRDE» пакета забыл проверить, действительно ли функция DO_MAGIC вызывает исключение, когда вход не является численным.
Благодаря этим инструментам (и людям, которые написали их), легче стать лучшим программистом R.
Я предлагаю выслушать эти советы и следовать этим.
Если кто -то не согласен с советом экспертов, мне всегда любопытно узнать, почему. Эксперты выбрали эти стандарты по причине. И эти эксперты также знают о аргументах, способствующих другим стандартам.
Для моих учеников я применяю чистый журнал «Oclint» и «GoodPractice» и покрытие кода не менее 95%.
Эти методы могут использоваться всеми от начала до опытных программистов. Для разработки зубной нить Github, Travis CI и Codecov бесплатны, в то время как разработка с закрытым исходным кодом требует платы.
Code better. Sleep better. [Langr, 2013]
При очистке всех тестов и высокого покрытия кода это может быть показано миру. Это может быть сделано, добавив значки сборки в файл readme.md в главной папке GitHub. Такие значки выглядят так:
Рисунок 15. Значки, отображаемые на GitHub 'prde
Чтобы отобразить эти значки, добавьте следующий код в readme.md в главную папку GitHub:
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
Листинг 4. Отображение значков статуса
Я надеюсь, что это вдохновит других людей сделать то же самое. Это сделало это для меня.
В этой статье вы узнали, как позволить себе исправить себя, отклоняясь от хорошей практики экспертов.
Мы создали и активировали две учетные записи веб -сайтов и написали один текстовый файл. Время, которое нам потребовалось, настройка этих инструментов будет возвращено из будущих изменений в нашем пакете.
Я хотел бы поблагодарить Луиса Буллоса, Рампала С. Этьенна и Сайруса А. Мэллона за их отзыв о более ранних проектах этой статьи.
git push : команда GIT для загрузки модифицированного кода на хост репозитория GIT
