sdj_raising_your_code_to_professional_standards
1.0.0
이것은 https://sdjournal.org/raising-code-professional-standards에서 sdjournal 에 게시 된 기사의 대략적인 버전입니다. 내 기사는 무료 섹션에 있으며 GitHub 계정으로 가입 할 수 있습니다.
당신은 잘하고 싶습니다. 모든 전문가 지침을 따르는 패키지를 작성하는 법을 배우고 싶습니다. 귀하는 전문적인 도구에 의해 수정 될 수 있으며 배우는 것입니다. 당신은 프로처럼 프로그램하고 싶습니다. 당신은 당신이 자랑스럽게 생각하는 패키지를 만들고 싶습니다.
그런 다음이 기사를 읽어야합니다.
코딩 표준 및 코드 적용 범위 및 모범 사례에 대한 자동 테스트를 추가하는 법을 배웁니다. 이것은 모두 패키지의 코드를 github에 업로드하는 명령을 푸시 푸시 에 의해 트리거됩니다.
예제 패키지를 테스트 케이스로 사용하겠습니다.
결국, 당신은 당신이 프로처럼 일하도록 강요하는 대본을 가질 것입니다.
당신이 방법을 알고 있다고 가정합니다
아직 R 기능을 읽을 수없는 경우 [Matloff, 2011]를 읽거나 'Swirl'패키지를 사용하는 것이 좋습니다.
패키지를 쓸 수 없거나 테스트를 사용하거나 github를 알고있는 경우 [Hadley, 2015]를 읽는 것이 좋습니다.
저는 업계의 최고 수준에 따라 프로그래밍을 가르치는 것을 좋아합니다. 7-77 세의 저의 학생들은 모두 Andrew Hunt와 David Thomas의 'The Pragmatic 프로그래머'의 문헌의 조언을 따옴표에 직면하고 있습니다. R에 관해서는 Hadley Wickham의 모든 조언을 인용하고 싶습니다.
전문가의 모범 사례에 따라 코드 개발에 시간이 절약됩니다.
이 기사의 설정은 이러한 모범 사례 중 일부를 따릅니다. 이 관행은 합리적인 코딩 표준이며, 높은 코드 적용 범위가 있으며 (모든 코드가 테스트 됨) 실용적인 방식으로 R을 사용합니다.
이 기사에서는 전문가의 도움을받는 방법을 보여 드리겠습니다.
먼저 'PRDE'패키지를 소개하겠습니다 ( 'Professional R Development Example'). 이 패키지는이 기사의 설정으로 결함이 어떻게 노출되는지 보여주는 테스트 케이스 역할을합니다. 따라서 패키지는 의도적으로 결함이 있지만 모든 CRAN 테스트를 통과합니다. 'PRDR'은 GitHub에서 호스팅됩니다.
그런 다음 GitHub 계정과 완벽하게 상호 작용할 두 웹 사이트에 대한 계정을 설정하는 방법을 보여줍니다. 이들은 자동 테스트 (나중에 자세한 내용)를 설정하기위한 Travis CI와 패키지 코드의 적용 범위를 추적하는 CodeCov입니다 (나중에 자세한 내용).
모든 웹 사이트를 활성화하려면 파일이 패키지의 GitHub에 업로드되어 Travis CI 및 CodeCov 웹 사이트의 응답을 유발합니다. 이 응답을 하나씩 논의하겠습니다.
테스트 사례는 'PRDE'라는 패키지로, [Wickham, 2015]에 설명 된 구조를 따릅니다. 패키지는 GitHub에서 호스팅됩니다.
그림 1. 패키지 'Prde'의 github
'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)
})
Listing 2. do_magic 테스트
이 테스트는 기존 위치의 파일에 저장되며 테스트/테스트/test-do_magic.r 입니다. 테스트는 모두 통과합니다. 패키지가 rstudio에서 구축되거나 DevTools :: Check ()를 사용하여 확인 될 때 오류가 없습니다. 즉, 패키지가 문제없이 Cran으로 전송 될 수 있음을 의미합니다 (패키지가 관련이 있음을 제외하고는 제외)!
연속 통합은 변경된 코드를 GITHUB에 업로드 한 후 변경된 코드의 효과가 짧은 시간 후에 자동으로 표시됨을 의미합니다. 다시 말해 : 도입 된 결함으로 패키지가 더 이상 구축 할 수없는 경우 (예를 들어, 이제 실패한 테스트에 의해) 일찍 눈에 띄게됩니다. 또는 다른 사람이 그것을 깨뜨리면 팀은 일찍 눈치 채게됩니다. 또한 누군가가 풀 요청을 제출하면 패키지를 수락하기 전에 패키지를 구축 할 수 있는지 확인할 수 있습니다.
Jenkins, Codeship, Circleci 및 Wercker와 같은 다른 지속적인 통합 서비스가 많이 있습니다. 방금 Travis CI를 먼저 배웠습니다.
그림 2. 트래비스 CI 로고
설정의 첫 번째 단계는 Travis CI를 활성화하는 것입니다.
Travis CI는 Floss 소프트웨어를 개발할 때 무료로 사용할 수 있으며 Github에서 잘 작동하는 지속적인 통합 서비스 (이름의 'CI')입니다.
먼저 Travis CI를 활성화하겠습니다. 활성화 된 경우에만 GitHub에 업로드시 실행되기 때문입니다.
이렇게하려면 : Travis CI 웹 사이트 www.travis-ci.org 를 방문하여 Github 계정으로 로그인하십시오. Travis는 사용자 이름 및 이메일과 같은 일부 Github 정보에 대한 권한을 요청합니다. 승인 후 Travis CI는 모든 사용자의 GitHub 리포지토리 및 활성화 상태를 보여줍니다.
그림 3. Travis CI가 확인한 GitHubs 개요
이 그림에서, 사용자는 적어도 3 개의 Github 리포지토리를 가지고 있으며, 그 중 하나는 활성화되지 않았고 (회색 십자가) 2 개는 (녹색 검사)입니다.
r 패키지의 github를 찾아 활성화하십시오.
코드 적용 범위는 테스트에서 다루는 코드 라인의 백분율입니다. 줄이 테스트되지 않은 경우, 죽은 코드가 감지되거나 (제거 할 수 있음) 해당 코드를 사용하는 테스트를 작성해야합니다. 코드 적용 범위는 코드 품질과 관련이 있습니다 [Del Frate et al., 1995].
코드 기후, Codacity, Coverals, QuantifiedCode 등과 같은 코드 커버리지를 추적하는 다른 서비스가 있습니다. 우리가 사용하는 패키지 ( 'lintr')는 codecov를 사용하는 것입니다.
그림 4. Codecov 로고
두 번째 단계는 Codecov를 활성화하는 것입니다.
Codecov는 Github Repository의 코드 커버리지를 사용자 친화적 인 형태로 보여주는 웹 사이트입니다. Codecov는 시간이 지남에 따라 프로젝트의 코드 커버리지를 추적합니다. 여러 개의 git 분기가있는 경우 각 지점마다 코드 적용 범위가별로 표시됩니다.
우리는 지금 Codecov를 활성화해야합니다
CodeCov는 등록 된 사용자의 코드 적용 범위 만 받고 표시합니다.
Codecov를 활성화하려면 웹 사이트 https://codecov.io 로 이동하여 Github 계정으로 로그인하십시오. 사용자 이름 및 이메일과 같은 일부 GitHub 정보에 대한 승인을 요청합니다.
승인 후 CodeCov는 모든 사용자의 GitHubs의 코드 범위를 표시합니다. 새 사용자의 경우 코드의 적용 범위가 아직 측정되지 않았 으므로이 화면은 대부분 비어 있습니다. 여러 GitHub 리포지토리의 코드 커버리지가 측정 된 사용자의 경우 CodeCov 화면이 다음과 같습니다.
그림 5 : Codecov가 확인한 GitHubs의 예제
이 그림에서는 코드 커버리지를 확인한 최소 3 개의 GitHub 리포지토리가있는 용도를 볼 수 있습니다.
세 번째 단계는 Travis CI에 새 코드가 활성화 된 GitHub에 업로드 될 때해야 할 일을 지시하는 것입니다.
Travis는 .travis.yml 이라는 일반 텍스트 파일 인 빌드 스크립트를 사용하여해야 할 일을 지시합니다. 파일 이름은 DOT로 시작하여 UNIX Systems에서 숨겨진 파일이됩니다. '.yml'확장은 '또 다른 마크 업 언어'의 약어입니다. Travis CI는 Bash Command Language로 지시됩니다.
프로젝트의 루트 폴더에서 .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. Travis CI 스크립트
이것은 간단하고 간단한 .travis.yml 스크립트입니다. 첫 번째 줄은 여기에 사용 된 프로그래밍 언어는 R이라고 명시되어 있습니다. 두 번째 줄은 Travis CI 에게이 패키지의 불필요한 재설치를 방지하기 위해 설치된 패키지를 캐시에 보관하도록 지시합니다. 'r_github_packages'섹션은 Travis CI 에이 Github 호스팅 패키지를 설치하도록 지시합니다. 패키지가 DevTools :: Check ()를 통과 한 후 '후_success'섹션은 실행됩니다. 이 섹션에서는 'Lintr', 'Covr'및 'GoodPractice'패키지에서 확인을 실행합니다. 나중에 그 패키지에 대해 더 많이.
이 .travis.yml 파일을 만든 후 github에 업로드하십시오.
github에 .travis.yml을 업로드하면 Github에서 즉시 볼 수 있습니다.
그림 6. Travis CI 빌드 스크립트를 추가 한 후 'PRDE'github
이 github 로의 푸시는 Travis CI를 트리거하며 즉시 작업을 시작합니다.
Travis CI는 가상 머신을 설정하는 데 약간의 시간이 필요합니다. GitHub에 업로드 할 때마다 재현 가능한 빌드 및 테스트 환경을 보장하기 위해 가상 머신이 생성됩니다.
Travis CI가 작업을 수행하는 것을 보려면 Travis CI 웹 사이트 https://travis-ci.org 로 돌아갑니다. 약 1 분 후 Travis CI의 진행 상황이 보이게됩니다. Travis CI는 먼저 모든 패키지와 종속성을 설치합니다. .travis.yml 스크립트는 모든 패키지를 캐시하여 두 번째 빌드를 더 빠르게 만듭니다.
다음은 'PRDE'패키지의 헤더입니다. 첫 번째 빌드입니다.
그림 7. 'PRDE'패키지의 헤더 첫 번째 빌드
우리는 이미 Rstudio에서 확인되었으므로 패키지 가이 수표를 통과 할 것임을 이미 알고 있습니다. 빌드가 통과되지 않으면 DevTools :: Check ()가 주어진 것과 동일한 출력이 표시되고 더 이상 아무것도 표시되지 않습니다. 빌드가 통과되면 맨 아래에 몇 가지 새로운 정보가 있습니다.
그림 8. 'PRDE'패키지의 하단 첫 번째 빌드
왼쪽의 삼각형을 클릭하면 몇 가지 추가 정보가 표시됩니다.
먼저 'Lintr'패키지 (Jim Hester)에서 피드백을 확장 할 것입니다. 그것은 다음을 보여준다 :
그림 9. 'Lintr'패키지에 의해 제공된 피드백
'Lintr'은 코딩 스타일 패키지가 Wickham (2014) 및 Wickham (2015)과 같이 잘 알려진 표준을 따르는 패키지를 확인하는 패키지입니다.
그림 10. Jim Hester
'Lintr'의 출력은 Travis CI 웹 사이트에만 표시되지 않습니다. 또한 내 좋은 친구 Lintr-Bot은 똑같은 메시지와 함께 Github의 커밋에 대해 언급 할 것입니다.
그림 11. github에 표시된대로 커밋에 대한 Lintr-Bot의 의견
Lintr-Bot은 항상 옳습니다. 필요한 경우 'Lintr'은 다른 코딩 표준을 허용하도록 할 수 있습니다.
그림 12. Mangothecat 로고
Lintr-Bots의 지혜의 말에서 계속해서 'GoodPractice'패키지 (Mangothecat)에서 피드백을 확장 할 것입니다. 이것은 다음과 같습니다.
그림 13. 'GoodPractice'패키지에 의해 제공된 피드백
'GoodPractice'는 모범 사례를 추가하여 'Lintr'을 확장합니다. 예를 들어, 특정 기능을 사용하지 않고 대신 더 나은 대안을 사용하는 것이 좋습니다.
Travis 빌드 로그에 'COVR'패키지에 대한 호출에 대한 정보를 제공하는 세 번째 삼각형이 확장 될 수 있습니다. 이 정보를 여기에서 보는 것은 원유 형태로 표시되므로 도움이되지 않습니다. 대신 Codecov 웹 사이트 https://codecov.io로 돌아가서 코드 커버리지를 더 예쁘게보십시오.
그림 14. Covecov에 표시된 'COVR'패키지에 의해 주어진 피드백
코드 적용 범위는 'PRDE'패키지의 저자가 DO_MAGIC 함수가 실제로 입력이 숫자가 아닐 때 예외가 발생하는지 테스트하는 것을 잊었음을 보여줍니다.
이 덕분에 도구 (그리고 그 글을 쓴 사람들) 덕분에 더 나은 R 프로그래머가되기가 더 쉽습니다.
나는이 조언을 듣고 이것을 따르라고 제안합니다.
전문가의 조언에 동의하지 않는다면 항상 이유를 알고 싶어합니다. 전문가들은 이유 때문에 이러한 표준을 선택했습니다. 그리고 그 전문가들은 또한 다른 표준을 선호하는 주장을 알고 있습니다.
학생들에게는 깨끗한 'oclint'와 'goodpractice'로그와 95%이상의 코드 커버리지를 시행합니다.
이러한 기술은 처음부터 숙련 된 프로그래머까지 모든 사람이 사용할 수 있습니다. Floss Development의 경우 Github, Travis CI 및 Codecov는 무료이며 폐쇄 소스 개발은 수수료를 안정합니다.
Code better. Sleep better. [Langr, 2013]
모든 테스트가 지워지고 높은 코드 적용 범위를 가질 때, 이것은 세계에 나타날 수 있습니다. 이는 GitHub의 기본 폴더에서 Build 배지를 readme.md 파일에 추가하여 수행 할 수 있습니다. 그런 배지는 다음과 같습니다.
그림 15. 배지는 'prde'github에 표시됩니다
이러한 배지를 표시하려면 GitHub의 기본 폴더에서 다음 코드를 readme.md 에 추가하십시오.
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
목록 4. 상태 배지 표시
다른 사람들이 똑같이하도록 영감을주기를 바랍니다. 그것은 나를 위해 그렇게했습니다.
이 기사에서는 전문가의 모범 사례에서 벗어날 때 자신을 교정하는 방법을 배웠습니다.
우리는 두 개의 웹 사이트 계정을 만들고 활성화하고 하나의 텍스트 파일을 작성했습니다. 이 도구를 설정하는 시간은 미래의 RANCKING에서 R 패키지로 돌아갈 것입니다.
이 기사의 초안에 대한 피드백에 대해 Luis Boullosa, Rampal S. Etienne 및 Cyrus A. Mallon에게 감사의 말씀을 전합니다.
git push : 수정 된 코드를 git 리포지토리 호스트에 업로드하는 git 명령
