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存储库主机
