sdj_raising_your_code_to_professional_standards
1.0.0
Ini adalah versi kasar dari artikel yang diterbitkan di sdjournal , di https://sdjournal.org/raising-code-professional-standards. Artikel saya ada di bagian gratis dan Anda dapat mendaftar dengan akun GitHub.
Anda ingin menjadi baik. Anda ingin belajar menulis paket yang mengikuti semua pedoman ahli. Anda terbuka untuk dikoreksi oleh alat profesional apa pun dan belajar darinya. Anda ingin memprogram seperti pro. Anda ingin membuat paket yang Anda banggakan.
Maka Anda harus membaca artikel ini.
Anda akan belajar menambahkan pengujian otomatis untuk pengkodean standar dan cakupan kode dan praktik yang baik. Ini semua dipicu oleh git dorong perintah yang mengunggah kode paket Anda ke github -nya.
Kami akan menggunakan paket contoh sebagai test case.
Pada akhirnya, Anda akan memiliki skrip yang memaksa Anda untuk bekerja seperti pro.
Diasumsikan Anda tahu bagaimana caranya
Jika Anda belum dapat membaca fungsi R, saya sarankan membaca [Matloff, 2011] atau menggunakan paket 'Swirl'.
Jika Anda tidak dapat menulis paket, menggunakan testthat atau tahu github, saya sarankan membaca [Hadley, 2015].
Saya menikmati mengajarkan pemrograman mengikuti standar tertinggi industri. Murid-murid saya, berusia 7-77 tahun, semuanya dihadapkan dengan kutipan nasihat dari literatur, terutama dari 'programmer pragmatis' oleh Andrew Hunt dan David Thomas. Mengenai R, saya suka mengutip semua saran dari Hadley Wickham.
Mengikuti praktik baik para ahli akan menghemat waktu dalam mengembangkan kode.
Pengaturan artikel ini mengikuti beberapa praktik bagus ini. Praktiknya adalah standar pengkodean rasional, memiliki cakupan kode tinggi (semua kode diuji), dan menggunakan R dengan cara pragmatis.
Dalam artikel ini, saya akan menunjukkan bagaimana dibantu oleh para ahli.
Pertama, saya akan memperkenalkan paket 'PRDE' ('Contoh Pengembangan Profesional'). Paket ini berfungsi sebagai kasus uji untuk menunjukkan bagaimana kekurangannya diekspos oleh pengaturan artikel ini. Dengan demikian, paket ini cacat dengan sengaja, namun lulus semua tes cran. 'PRDR' diselenggarakan di GitHub.
Lalu saya menunjukkan cara mengatur akun untuk dua situs web yang akan berinteraksi mulus dengan akun GitHub. Ini adalah Travis CI, untuk mengatur pengujian otomatis (lebih lanjut tentang itu nanti), dan Codecov yang melacak cakupan kode paket (lebih lanjut tentang itu nanti).
Setelah semua situs web diaktifkan, sebuah file diunggah ke github paket, yang akan memicu tanggapan oleh situs web Travis CI dan Codecov. Saya akan membahas tanggapan ini satu per satu.
Kasing uji adalah paket yang disebut 'PRDE', yang mengikuti struktur yang dijelaskan dalam [Wickham, 2015]. Paket ini di -host di github:
Gambar 1. GitHub paket 'PRDE'
Di dalam paket 'PRDE' berada di fungsi, yang disebut do_magic , seperti ini:
#' 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;
}
Daftar 1. Fungsi 'Do_Magic'
Fungsi do_magic disimpan dalam file di lokasi konvensional, yaitu r/do_magic.r . Ini didokumentasikan menggunakan paket 'roxygen2'. Fungsi memeriksa input yang benar, dan gagal cepat jika tidak dapat memprosesnya.
Paket ini memiliki beberapa tes, menggunakan 'testThat', seperti yang ditunjukkan di bawah ini:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
Daftar 2. Tes Do_magic
Tes ini disimpan dalam file di lokasi konvensional, yang merupakan tes/testThat/test-do_magic.r . Semua tes lulus. Tidak ada kesalahan yang ditemukan ketika paket diperiksa untuk membangun rstudio atau menggunakan devtools :: check () . Itu berarti paket dapat dikirim ke cran tanpa masalah (kecuali untuk meyakinkan bahwa paket itu relevan)!
Integrasi berkelanjutan berarti bahwa efek dari kode yang diubah, setelah mengunggahnya ke GitHub, ditampilkan secara otomatis setelah waktu yang singkat. Dengan kata lain: Jika paket tidak dapat dibangun lagi dengan cacat yang diperkenalkan (oleh, misalnya, tes yang sekarang gagal), itu akan diperhatikan lebih awal. Atau, jika orang lain memecahkannya, tim akan melihat lebih awal. Juga, ketika seseorang mengirimkan permintaan tarik, orang dapat melihat apakah itu akan merusak membangun paket sebelum menerimanya.
Ada banyak layanan integrasi kontinu lainnya yang bekerja dengan baik, seperti Jenkins, Codeship, Circleci dan Wercker. Saya kebetulan belajar Travis CI terlebih dahulu.
Gambar 2. Logo Travis CI
Langkah pertama dari pengaturan kami adalah mengaktifkan Travis CI.
Travis CI adalah layanan integrasi berkelanjutan (karenanya, 'CI' dalam nama) yang bebas digunakan saat mengembangkan perangkat lunak benang dan bekerja dengan baik dengan GitHub.
Pertama -tama mari kita aktifkan Travis CI, karena hanya ketika diaktifkan, akan mulai berjalan di atas unggahan ke GitHub.
Untuk melakukan ini: Pergi ke situs web Travis CI, www.travis-ci.org , dan masuk dengan akun GitHub. Travis meminta otorisasi untuk beberapa informasi github, seperti nama pengguna dan email. Setelah otorisasi, Travis CI menunjukkan semua repositori github pengguna dan status aktivasi mereka:
Gambar 3. Gambaran Umum GitHub yang Diperiksa oleh Travis CI
Dalam gambar ini, pengguna ditunjukkan yang memiliki setidaknya tiga repositori gitub, yang satu tidak diaktifkan (salib abu -abu) dan dua adalah (cek hijau).
Temukan github dari paket R dan aktifkan.
Cakupan kode adalah persentase baris kode yang dicakup oleh tes. Jika suatu garis tidak teruji, kode mati terdeteksi (yang dapat dihapus) atau tes harus ditulis yang memang menggunakan kode itu. Cakupan kode berkorelasi dengan kualitas kode [Del Frate et al., 1995].
Ada layanan lain yang melacak cakupan kode, seperti iklim kode, kodabity, coverall, quantifiedCode dan banyak lagi. Kebetulan paket yang akan kita gunakan ('LINTR') menggunakan Codecov.
Gambar 4. Logo Codecov
Langkah kedua adalah mengaktifkan Codecov.
Codecov adalah situs web yang menunjukkan cakupan kode repositori GitHub dalam bentuk yang ramah pengguna. Codecov melacak cakupan kode proyek sepanjang waktu. Jika ada beberapa cabang Git, cakupan kode ditampilkan secara terpisah untuk setiap cabang.
Kita perlu mengaktifkan codecov sekarang, karena
Codecov hanya akan menerima dan menampilkan cakupan kode pengguna terdaftar.
Untuk mengaktifkan Codecov, buka situs webnya, https://codecov.io , dan masuk dengan akun GitHub. Ini akan meminta otorisasi untuk beberapa informasi github, seperti nama pengguna dan email.
Setelah otorisasi, Codecov menampilkan cakupan kode dari semua githubs pengguna. Untuk pengguna baru, layar ini sebagian besar akan kosong, karena belum ada cakupan kode yang diukur. Untuk pengguna yang memiliki beberapa cakupan kode repositori gitub yang diukur, layar Codecov akan terlihat seperti ini:
Gambar 5: Contoh Gambaran Umum GitHub yang Diperiksa oleh Codecov
Dalam gambar ini, orang dapat melihat kegunaan yang memiliki setidaknya tiga repositori GitHub yang memeriksakan cakupan kode mereka.
Langkah ketiga adalah menginstruksikan Travis CI apa yang harus dilakukan ketika kode baru diunggah ke github yang diaktifkan.
Travis diinstruksikan apa yang harus dilakukan menggunakan skrip build, yang merupakan file plaintext bernama .travis.yml . Nama file dimulai dengan titik, yang membuatnya menjadi file tersembunyi di sistem UNIX. Perpanjangan '.yml' adalah singkatan dari 'bahasa markup lain'. Travis CI diinstruksikan dalam bahasa komando bash.
Di folder root proyek, buat file bernama .travis.yml , dan masukkan teks berikut:
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()"
Listing 3. The Travis CI Script
Ini adalah skrip .travis.yml yang sederhana dan langsung. Baris pertama menyatakan bahwa bahasa pemrograman yang digunakan di sini adalah R. Baris kedua memberi tahu Travis CI untuk menyimpan paket yang diinstal dalam cache, untuk mencegah instal ulang paket ini yang tidak perlu. Bagian 'R_Github_Packages' menginstruksikan Travis CI untuk menginstal paket-paket yang di-host gitub ini. Bagian 'After_Success' dijalankan setelah paket melewati devtools :: check () . Di bagian ini, itu akan menjalankan cek dari paket 'lintr', 'covr' dan 'goodpractice'. Lebih lanjut tentang paket -paket itu nanti.
Setelah membuat file .travis.yml ini, unggah ke GitHub.
Setelah mengunggah .travis.yml ke github, itu akan terlihat segera di github:
Gambar 6. Gitub 'PRDE' setelah menambahkan skrip build travis ci
Dorongan ini ke Github memicu Travis CI dan akan segera mulai melakukan pekerjaannya.
Travis CI membutuhkan waktu untuk mengatur mesin virtual. Setiap kali unggahan ke GitHub dibuat, mesin virtual dibuat, untuk memastikan lingkungan build dan uji yang dapat direproduksi.
Untuk melihat Travis CI melakukan pekerjaannya, kembali ke situs web Travis CI, https://travis-ci.org . Setelah sekitar satu menit, kemajuan Travis CI menjadi terlihat. Travis CI pertama -tama menginstal semua paket dan ketergantungannya. Script .travis.yml menyimpan semua paket, membuat yang kedua lebih cepat.
Berikut adalah header paket 'PRDE' yang dibangun pertama:
Gambar 7. Header dari paket 'PRDE'
Kami sudah tahu paket itu akan lulus cek ini, karena ini telah diperiksa di rstudio. Jika build tidak berlalu, output yang sama akan ditampilkan seperti yang diberikan oleh DevTools :: check () dan tidak lebih. Jika build tidak berlalu, akan ada beberapa informasi baru di bagian bawah:
Gambar 8. Bawah paket 'PRDE'
Mengklik segitiga di sebelah kiri mengungkapkan beberapa informasi tambahan.
Pertama, kami akan memperluas umpan balik dari paket 'LINTR' (oleh Jim Hester). Itu menunjukkan:
Gambar 9. Umpan balik yang diberikan oleh paket 'LINTR'
'LINTR' adalah paket untuk memeriksa apakah paket gaya pengkodeannya mengikuti standar yang diaktifkan dengan baik, seperti yang ada di Wickham (2014) dan Wickham (2015).
Gambar 10. Jim Hester
Output 'LINTR' tidak hanya ditampilkan di situs web Travis CI. Teman baik saya Lintr-Bot akan mengomentari komit di GitHub, dengan pesan yang persis sama:
Gambar 11. Komentar oleh lintr-bot pada komit, seperti yang ditunjukkan pada github
LINTR-BOT selalu benar. Jika diperlukan, 'LINTR' dapat dibuat untuk memungkinkan standar pengkodean lainnya.
Gambar 12. Logo Mangothecat
Beralih dari Lintrr-Bots Words of Wisdom, kami akan memperluas umpan balik dari paket 'Goodpractice' (oleh Mangothecat). Yang ini menunjukkan:
Gambar 13. Umpan balik yang diberikan oleh paket 'GoodPractice'
'Goodpractice' memperluas 'lINTR' dengan menambahkan praktik yang baik. Misalnya, itu mungkin menyarankan untuk tidak menggunakan fungsi tertentu tetapi untuk menggunakan alternatif yang lebih baik sebagai gantinya.
Ada segitiga ketiga yang dapat diperpanjang, memberikan informasi tentang panggilan ke paket 'COVR', di Log Bangun Travis. Melihat informasi ini di sini tidak membantu, karena ditampilkan dalam bentuk kasar. Sebaliknya, kembali ke situs web Codecov, https://codecov.io, untuk melihat cakupan kode dengan cara yang lebih cantik:
Gambar 14. Umpan balik yang diberikan oleh paket 'COVR', seperti yang ditampilkan oleh Codecov
Cakupan kode menunjukkan, bahwa penulis paket 'PRDE' telah lupa untuk menguji jika fungsi DO_MAGIC memang melempar pengecualian ketika inputnya tidak numerik.
Berkat alat ini (dan orang -orang yang telah menulisnya) lebih mudah menjadi programmer R yang lebih baik.
Saya sarankan untuk mendengarkan saran ini dan mengikuti ini.
Jika seseorang tidak setuju atas saran para ahli, saya selalu ingin tahu mengapa. Para ahli telah memilih standar -standar itu karena suatu alasan. Dan para ahli itu juga menyadari argumen yang mendukung standar lain.
Untuk siswa saya, saya menegakkan log 'oclint' dan 'GoodPractice' yang bersih dan cakupan kode setidaknya 95%.
Teknik -teknik ini dapat digunakan oleh semua orang dari awal hingga pemrogram yang berpengalaman. Untuk pengembangan benang, GitHub, Travis CI dan Codecov gratis, sementara pengembangan sumber tertutup meminta biaya.
Code better. Sleep better. [Langr, 2013]
Saat semua tes dihapus dan cakupan kode tinggi, ini dapat ditunjukkan kepada dunia. Ini dapat dilakukan dengan menambahkan lencana build ke file readme.md , di folder utama GitHub. Lencana seperti itu terlihat seperti ini:
Gambar 15. Lencana yang ditampilkan pada github 'PRDE'
Untuk menampilkan lencana ini, tambahkan kode berikut ke readme.md di folder utama GitHub:
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
Daftar 4. Menampilkan Lencana Status
Saya berharap ini akan menginspirasi orang lain untuk melakukan hal yang sama. Itu melakukannya untuk saya.
Dalam artikel ini, Anda telah belajar bagaimana membiarkan diri Anda diperbaiki saat menyimpang dari praktik yang baik para ahli.
Kami telah membuat dan mengaktifkan dua akun situs web dan menulis satu file teks. Waktu yang dibutuhkan kami menyiapkan alat -alat ini akan dimenangkan kembali dari perubahan masa depan ke paket R kami.
Saya ingin mengucapkan terima kasih kepada Luis Boullosa, Rampal S. Etienne dan Cyrus A. Mallon atas umpan balik mereka pada draft sebelumnya dari artikel ini.
git push : Perintah git untuk mengunggah kode yang dimodifikasi ke host repositori git
