sdj_raising_your_code_to_professional_standards
1.0.0
這是sdjournal上發表的文章的粗略版本。我的文章在免費部分中，您可以通過GitHub帳戶註冊。
你想變得很好。您想學習編寫遵循所有專家指南的軟件包。您願意被任何專業工具糾正並從中學習。您想像專業人士一樣編程。您想創建一個您引以為傲的包裹。
然後，您應該閱讀本文。
您將學習為編碼標準和代碼覆蓋範圍和良好實踐添加自動測試。這一切都是由git推動命令觸發的，該命令將軟件包的代碼上傳到其github。
我們將使用示例軟件包作為測試用例。
最後，您將擁有一個劇本，迫使您像專業人士一樣工作。
假設您知道如何
如果您還不能閱讀R功能，建議您閱讀[Matloff，2011]或使用“漩渦”軟件包。
如果您無法編寫軟件包，使用Testthat或知道GitHub，我建議您閱讀[Hadley，2015]。
我喜歡按照行業的最高標準教授編程。我的學生7-77歲，都面臨著文學的名言，尤其是來自安德魯·亨特（Andrew Hunt）和戴維·托馬斯（David Thomas）的《務實程序員》。關於R，我喜歡引用Hadley Wickham的所有建議。
遵循專家的良好實踐將節省開發代碼的時間。
本文的設置遵循其中一些良好實踐。這些實踐是一個有理編碼標準，具有高碼覆蓋範圍（所有代碼均已測試），並以務實的方式使用R。
在本文中，我將展示如何得到專家的幫助。
首先，我將介紹“ PRDE”軟件包（“專業R開發示例”）。該軟件包用作測試案例，以顯示本文設置如何暴露其缺陷。因此，該軟件包是故意有缺陷的，但通過所有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)
})
清單2。 do_magic測試
該測試存儲在傳統位置的文件中，該位置是測試/testthat/test-do_magic.r 。測試全部通過。選中包裝以在rstudio或使用devtools :: check（）中構建的包裝時，找不到錯誤。這意味著可以將軟件包發送到Cran而沒有任何問題（除了說服包裹相關之外）！
連續集成意味著，將其上傳到GitHub後，更改代碼的效果在短時間後會自動顯示。換句話說：如果軟件包無法通過引入的漏洞（例如，現在失敗的測試）構建，則將很早就注意到。或者，如果其他人打破它，團隊會儘早注意到。另外，當某人提交拉動請求時，人們可以在接受包裹之前查看是否會破壞構建包。
還有許多其他連續的集成服務也可以正常工作，例如Jenkins，Codeship，Circleci和Wercker。我剛好首先學習Travis CI。
圖2。 TravisCI徽標
我們設置的第一步是激活Travis CI。
Travis CI是一項連續的集成服務（因此，名稱中的“ CI”）在開發牙線軟件時可以免費使用，並且可以與GitHub合作。
讓我們首先激活Travis CI，因為只有在激活時，它才會在上傳到GitHub時開始運行。
為此：訪問Travis CI網站www.travis-ci.org ，並使用GitHub帳戶登錄。 Travis請求授權提供一些GITHUB信息，例如用戶名和電子郵件。授權後，Travis CI顯示了所有用戶的GitHub存儲庫及其激活狀態：
圖3。由Travis CI檢查的GitHub的概述
在此圖中，顯示了一個至少具有三個GitHub存儲庫的用戶，其中一個未激活（灰色十字），兩個是（綠色檢查）。
去查找R包的github並激活它。
代碼覆蓋範圍是測試涵蓋的代碼行的百分比。如果未測試行，則檢測到死亡代碼（可以刪除），或者應寫入測試，以使用該代碼。代碼覆蓋範圍與代碼質量相關[Del Frate等，1995]。
還有其他服務可以跟踪代碼覆蓋範圍，例如代碼氣候，代碼，合併，量化代碼等等。恰好是我們將使用CodeCov的軟件包（'lintr'）。
圖4。 Codecov徽標
第二步是激活Codecov。
CodeCov是一個網站，以用戶友好的形式顯示GitHub存儲庫的代碼覆蓋範圍。 Codecov在整個時間內跟踪項目的代碼覆蓋範圍。如果有多個GIT分支，則每個分支都會單獨顯示代碼覆蓋範圍。
我們現在需要激活Codecov，因為
Codecov將僅接收並顯示註冊用戶的代碼覆蓋範圍。
要激活CodeCov，請訪問其網站https://codecov.io ，然後使用GitHub帳戶登錄。它將要求提供一些GITHUB信息的授權，例如用戶名和電子郵件。
授權後，Codecov顯示所有用戶GitHubs的代碼覆蓋範圍。對於新用戶，此屏幕將大部分為空，因為尚未衡量代碼的覆蓋範圍。對於具有多個GitHub存儲庫的代碼覆蓋範圍的用戶，Codecov屏幕將如下所示：
圖5：Codecov檢查的GitHubs的示例概述
在此圖中，可以看到至少有三個GitHub存儲庫的用途檢查其代碼覆蓋範圍。
第三步是指示Travis CI將新代碼上傳到激活的GitHub時該怎麼辦。
使用構建腳本指示特拉維斯（Travis）指導該怎麼辦，該腳本是名為.travis.yml的明文文件。文件名以DOT開頭，這使其成為Unix系統上的隱藏文件。 “ .yml”擴展是“另一種標記語言”的縮寫。 Travis 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。 TravisCI腳本
這是一個簡單明了的.travis.yml腳本。第一行指出，這裡使用的編程語言是R。第二行告訴Travis CI將安裝的軟件包保存在緩存中，以防止不必要的重新安裝這些軟件包。 “ R_GITHUB_PACKAGES”部分指示Travis CI安裝這些GitHub託管軟件包。 “ after_success”部分是在軟件包通過devtools :: check（）之後運行的。在本節中，它將從“ lintr”，“ covr”和“ goodpractice”軟件包運行檢查。稍後將更多地介紹這些包裹。
創建此.travis.yml文件後，將其上傳到github。
將.travis.yml上傳到github後，它將在github上立即看到：
圖6。添加Travis CI構建腳本後的“ prde” github
這將推向Github觸發Travis CI，並將立即開始完成工作。
Travis CI需要一些時間來設置虛擬機。每次上傳到GitHub時，都會創建虛擬機，以確保可重複的構建和測試環境。
要查看Travis CI完成工作，請返回Travis CI網站https://travis-ci.org 。大約一分鐘後，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。 JimHester
“ Lintr”的輸出不僅顯示在Travis CI網站上。另外，我的好朋友Lintr-Bot將對GitHub的提交發表評論，並帶有完全相同的消息：
圖11。林特·企業對提交的評論，如GitHub上所示
lintr-bot總是正確的。如果需要，可以製作“ lintr”以允許其他編碼標準。
圖12。 Mangothecat徽標
從智慧的林特（Lintr-Bots）詞開始，我們將從“ Good Practice”軟件包（由Mangothecat）擴展反饋。這個顯示：
圖13。由“良好實踐”軟件包給出的反饋
“ Good Practice”通過添加良好實踐來擴展“ Lintr”。例如，它可能建議不要使用特定功能，而是建議使用更好的替代方案。
可以擴展第三個三角形，在Travis Build Log中提供有關“ COVR”軟件包的呼叫的信息。在此處查看此信息無濟於事，因為它以粗製形式顯示。相反，請返回Codecov網站https://codecov.io，以更漂亮的方式查看代碼覆蓋範圍：
圖14。由Codecov顯示的“ COVR”軟件包給出的反饋
代碼覆蓋範圍顯示，“ PRDE”軟件包的作者忘記了測試DO_MAGIC函數是否確實在輸入不是數字時會引發異常。
多虧了這些工具（以及寫這些工具），成為更好的R程序員會更容易。
我建議聽這些建議並遵循這些建議。
如果有人不同意專家的建議，我總是很好奇知道為什麼。專家們選擇了這些標準是有原因的。這些專家也意識到有利於其他標準的論點。
對於我的學生，我強制執行乾淨的“ Oclint”和“ GoodPractice”日誌，並且代碼覆蓋率至少為95％。
這些技術從開始到經驗豐富的程序員都可以使用。對於牙線開發，Github，Travis CI和Codecov是免費的，而封閉源開發則徵收費用。
Code better. Sleep better. [Langr, 2013]
當所有測試清除和高碼覆蓋範圍時，可能會向世界展示。這可以通過將構建徽章添加到github的主文件夾中的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。顯示狀態徽章
我希望它會激發其他人這樣做。它為我做到了。
在本文中，您已經學會瞭如何在與專家的良好實踐偏離時，讓自己得到糾正。
我們創建並激活了兩個網站帳戶並寫了一個文本文件。我們設置這些工具所花費的時間將從未來的R包更改中贏得。
我要感謝Luis Boullosa，Rampal S. Etienne和Cyrus A. Mallon對本文早期草稿的反饋。
git push ：git命令將修改的代碼上傳到git存儲庫主機
