sdj_raising_your_code_to_professional_standards
1.0.0
これは、https：//sdjournal.org/raising-code-professional-standardsのsdjournalで公開された記事のラフバージョンです。私の記事は無料のセクションにあり、GitHubアカウントでサインアップできます。
あなたは元気になりたいです。専門家のガイドラインのすべてに従うパッケージを書くことを学びたいと思います。あなたはあらゆるプロフェッショナルなツールによって修正され、そこから学ぶことにオープンです。プロのようにプログラムしたいです。誇りに思っているパッケージを作成したいです。
次に、この記事を読む必要があります。
コーディングの標準とコードのカバレッジと良い慣行のための自動テストを追加することを学びます。これはすべて、 gitによってトリガーされ、パッケージのコードをGithubにアップロードするコマンドを押します。
サンプルパッケージをテストケースとして使用します。
最終的に、プロのように作業することを強制するスクリプトがあります。
あなたが方法を知っていると想定されています
R機能をまだ読むことができない場合は、[Matloff、2011]を読むか、「Swirl」パッケージを使用することをお勧めします。
パッケージを書くことができない場合は、test thatまたはkithubを知っている場合は、[Hadley、2015]を読むことをお勧めします。
私は、業界の最高水準に従ってプログラミングを教えることを楽しんでいます。 7〜77歳の私の学生はすべて、特にアンドリュー・ハントとデビッド・トーマスによる「実用的なプログラマー」からの文学からのアドバイスの引用に直面しています。 Rに関しては、ハドリー・ウィッカムからすべてのアドバイスを引用するのが好きです。
専門家の良い慣行に従うことで、コードの開発の時間を節約できます。
この記事のセットアップは、これらの良い実践のいくつかに従います。プラクティスは合理的なコーディング標準であり、コードカバレッジが高い（すべてのコードがテストされています）、実用的な方法でRを使用します。
この記事では、専門家の助け方を紹介します。
まず、パッケージ「PRDE」（「Professional R Developmentの例」）を紹介します。このパッケージは、この記事のセットアップによってその欠陥がどのようにさらされるかを示すためのテストケースとして機能します。したがって、パッケージには意図的に欠陥がありますが、すべてのCRANテストに合格します。 「PRDR」はGitHubでホストされています。
次に、GitHubアカウントとシームレスに対話する2つのWebサイトのアカウントを設定する方法を示します。これらは、自動テストをセットアップするためのTravis CI（詳細については後で詳しく説明します）と、パッケージコードのカバレッジを追跡するCodecovです（詳細については後で詳しく説明します）。
すべてのWebサイトをアクティブにすると、ファイルがパッケージのGitHubにアップロードされ、Travis CIおよびCodecov Webサイトによる応答がトリガーされます。これらの回答については1つずつ議論します。
テストケースは「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」パッケージを使用して文書化されています。関数は正しい入力をチェックし、これらを処理できない場合に速く障害を失います。
以下に示すように、パッケージには「テスト」を使用して、いくつかのテストがあります。
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
リスト2。DO_MAGICテスト
このテストは、従来の場所のファイルに保存されます。これは、テスト/test that/test-do_magic.rです。テストはすべて合格します。 rstudioに組み込まれるか、 devtools :: check（）を使用するためにパッケージをチェックしたときにエラーは見つかりません。つまり、パッケージは問題なくクランに送信できることを意味します（パッケージが関連することを納得させることを除いて）！
継続的な統合とは、GitHubにアップロードした後、変更されたコードの効果が短時間後に自動的に表示されることを意味します。言い換えれば、導入された欠陥によってパッケージがもう構築できない場合（たとえば、現在失敗したテストによって）、早期に気付かれます。または、他の誰かがそれを壊した場合、チームは早期に気付くでしょう。また、誰かがプルリクエストを提出すると、それを受け入れる前にパッケージの構築を壊すかどうかを確認できます。
Jenkins、Codeship、Circleci、Werckerのように、同様に機能する他の多くの継続的な統合サービスもあります。私はたまたま最初にトラビスCIを学びました。
図2。TravisCIロゴ
セットアップの最初のステップは、Travis CIをアクティブにすることです。
Travis CIは、Flossソフトウェアを開発するときに自由に使用できる継続的な統合サービス（したがって、名前の「CI」）です。
最初にTravis CIをアクティブにしましょう。アクティブ化された場合にのみ、GitHubへのアップロード時に実行を開始します。
これを行うには、Travis CI Webサイトwww.travis-ci.orgにアクセスして、githubアカウントでサインインします。 Travisは、ユーザー名や電子メールなど、いくつかのGitHub情報の許可を要求します。許可後、Travis CIはすべてのユーザーのGitHubリポジトリとそのアクティベーションステータスを示します。
図3。TravisCIによってチェックされたGithubsの概要
この図では、少なくとも3つのGitHubリポジトリを持つユーザーが表示されますが、そのうち1つはアクティブ化されていません（灰色のクロス）、2つはグリーンチェックです）。
Rパッケージのgithubを見つけてアクティブにします。
コードカバレッジは、テストでカバーされているコード行の割合です。行がテストされていない場合、死んだコードが検出され（削除できる）、またはそのコードを使用するテストをテストする必要があります。コードカバレッジは、コードの品質と相関しています[Del Frate et al。、1995]。
コードの気候、コダシティ、カバーオール、QuantifiedCodeなど、コードカバレッジを追跡する他のサービスがあります。たまたま使用するパッケージ（ 'lintr'）がCodecovを使用します。
図4。Codecovロゴ
2番目のステップは、Codecovをアクティブにすることです。
Codecovは、GitHubリポジトリのコードカバレッジをユーザーフレンドリーなフォームで示すWebサイトです。 Codecovは、プロジェクトのコードカバレッジを長期間追跡します。複数のgitブランチがある場合、各ブランチに対してコードカバレッジが別々に表示されます。
今、Codecovをアクティブにする必要があります
Codecovは、登録ユーザーのコードカバレッジのみを受け取り、表示します。
Codecovをアクティブにするには、Webサイトhttps://codecov.ioにアクセスし、GitHubアカウントでサインインします。ユーザー名や電子メールなど、一部のGitHub情報の許可を要求します。
承認後、CodeCovはすべてのユーザーのGitHubsのコードカバレッジを表示します。新しいユーザーの場合、コードのカバレッジはまだ測定されていないため、この画面はほとんど空です。複数のGitHubリポジトリのコードカバレッジを測定しているユーザーの場合、Codecov画面は次のようになります。
図5：CodecovがチェックしたGithubsの概要の例
この図では、コードカバレッジがチェックされている少なくとも3つのGitHubリポジトリを持つ使用法を見ることができます。
3番目のステップは、新しいコードがアクティブ化されたGitHubにアップロードされたときにTravis CIに何をすべきかを指示することです。
Travisは、 .travis.ymlという名前のプレーンテキストファイルであるビルドスクリプトを使用して何をすべきかを指示されます。ファイル名はドットで始まり、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であると述べています。2番目の行は、これらのパッケージの必要のない再インストールを防ぐために、Travis CIにインストールされたパッケージをキャッシュに保持するように指示します。 「r_github_packages」セクションは、これらのgithub-hostedパッケージをインストールするようにtravis CIに指示します。パッケージがdevtools :: check（）を通過した後、「afth_success」セクションは実行されます。このセクションでは、「lintr」、「covr」、「goodpractice」パッケージからチェックを実行します。これらのパッケージの詳細は後で。
この.travis.ymlファイルを作成した後、githubにアップロードします。
.travis.ymlをgithubにアップロードした後、githubですぐに表示されます。
図6。TravisCIビルドスクリプトを追加した後の「Prde」Github
GitHubへのこのプッシュはTravis CIをトリガーし、すぐにその作業を開始します。
Travis CIは、仮想マシンをセットアップする時間が必要です。 GitHubへのアップロードが作成されるたびに、再現可能なビルドおよびテスト環境を確保するために、仮想マシンが作成されます。
Travis CIがその仕事をするのを見るには、Travis CIのWebサイトhttps://travis-ci.orgに戻ります。約1分後、Travis CIの進捗状況が表示されます。 Travis CIは、最初にすべてのパッケージとその依存関係をインストールします。 .travis.ymlスクリプトはすべてのパッケージをキャッシュし、2番目のビルドをより速くします。
「PRDE」パッケージのヘッダーは、最初のビルドです。
図7。「PRDE」パッケージのヘッダーその最初のビルド
これはすでにrstudioでチェックされているため、パッケージがこのチェックに合格することをすでに知っています。ビルドが通過しない場合、 DevTools :: Check（）によって与えられた同じ出力が表示されます。ビルドが通過する場合、下部に新しい情報があります。
図8。「PRDE」パッケージの下部ビルド
左の三角形をクリックすると、いくつかの追加情報が明らかになります。
まず、「Lintr」パッケージ（Jim Hesterによる）からフィードバックを拡張します。それは示しています：
図9。「LINTR」パッケージで与えられたフィードバック
「LINTR」は、Wickham（2014）やWickham（2015）のような、そのコーディングスタイルが十分にアクセスされた基準に従うかどうかを確認するためのパッケージです。
図10。ジム・ヘスター
「Lintr」の出力は、Travis CI Webサイトに表示されるだけではありません。また、私の親友であるLintr-Botは、まったく同じメッセージでGitHubでのコミットについてコメントします。
図11。githubに示されているように、コミットに関するlintr-botによるコメント
lintr-botは常に正しいです。必要に応じて、他のコーディング標準を可能にするために「lintr」を作成できます。
図12。マンゴテキャットロゴ
Lintr-Botsの知恵の言葉から進むには、「Good Practice」パッケージ（Mangothecat）からのフィードバックを拡張します。これは次のことを示しています。
図13。「GoodPractice」パッケージで与えられたフィードバック
「GoodPractice」は、Good Practicesを追加することで「Lintr」を拡張します。たとえば、特定の機能を使用するのではなく、代わりにより良い代替品を使用することを示唆する場合があります。
拡張できる3番目の三角形があり、Travisビルドログに「Covr」パッケージへの呼び出しに関する情報を提供します。ここでこの情報を表示することは、粗い形式で表示されるため、役に立ちません。代わりに、CodecovのWebサイト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。ステータスバッジの表示
他の人に同じことをするように促すことを願っています。それは私のためにそうしました。
この記事では、専門家の良い実践から逸脱するときに自分を修正する方法を学びました。
2つのWebサイトアカウントを作成およびアクティブにし、1つのテキストファイルを作成しました。これらのツールのセットアップがかかった時間は、将来の変更からRパッケージの変更から取り戻されます。
Luis Boullosa、Rampal S. Etienne、Cyrus A. Mallonに、この記事の以前のドラフトに関するフィードバックに感謝します。
git push ：gitコマンドをgitリポジトリホストにアップロードするためのコマンド
