sdj_raising_your_code_to_professional_standards
1.0.0
นี่เป็นเวอร์ชันคร่าวๆของบทความที่ตีพิมพ์ที่ sdjournal ที่ https://sdjournal.org/raising-code-professional-standards บทความของฉันอยู่ในส่วนฟรีและคุณสามารถลงทะเบียนกับบัญชี GitHub
คุณอยากเป็นคนดี คุณต้องการเรียนรู้ที่จะเขียนแพ็คเกจที่เป็นไปตามแนวทางของผู้เชี่ยวชาญทั้งหมด คุณเปิดรับการแก้ไขโดยเครื่องมือระดับมืออาชีพและเรียนรู้จากมัน คุณต้องการโปรแกรมเช่นเดียวกับข้อดี คุณต้องการสร้างแพ็คเกจที่คุณภูมิใจ
จากนั้นคุณควรอ่านบทความนี้
คุณจะได้เรียนรู้ที่จะเพิ่มการทดสอบอัตโนมัติสำหรับมาตรฐานการเข้ารหัสและการครอบคลุมรหัสและแนวทางปฏิบัติที่ดี ทั้งหมดนี้ถูกเรียกใช้โดย Git Push คำสั่งที่อัปโหลดรหัสแพ็คเกจของคุณไปยัง GitHub
เราจะใช้แพ็คเกจตัวอย่างเป็นกรณีทดสอบ
ในท้ายที่สุดคุณจะมีสคริปต์ที่บังคับให้คุณทำงานเหมือนมืออาชีพ
สันนิษฐานว่าคุณรู้วิธีการ
ในกรณีที่คุณยังไม่สามารถอ่านฟังก์ชั่น R ฉันขอแนะนำให้อ่าน [Matloff, 2011] หรือใช้แพ็คเกจ 'Swirl'
ในกรณีที่คุณไม่สามารถเขียนแพ็คเกจใช้ testhat หรือรู้ GitHub ฉันขอแนะนำให้อ่าน [Hadley, 2015]
ฉันสนุกกับการสอนการเขียนโปรแกรมตามมาตรฐานสูงสุดของอุตสาหกรรม นักเรียนของฉันอายุ 7-77 ปีทั้งหมดเผชิญหน้ากับคำแนะนำของคำแนะนำจากวรรณกรรมโดยเฉพาะอย่างยิ่งจาก 'The Pragmatic Programmer' โดย 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. gitHub ของแพ็คเกจ 'prde'
ภายในแพ็คเกจ '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' ฟังก์ชั่นตรวจสอบอินพุตที่ถูกต้องและล้มเหลวอย่างรวดเร็วหากไม่สามารถประมวลผลสิ่งเหล่านี้ได้
แพ็คเกจมีการทดสอบบางอย่างโดยใช้ 'testhat' ดังที่แสดงด้านล่าง:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
รายการ 2. การทดสอบ do_magic
การทดสอบนี้จะถูกเก็บไว้ในไฟล์ในตำแหน่งทั่วไปซึ่งคือ การทดสอบ/ทดสอบ/ทดสอบ-DO_MAGIC.R การทดสอบทั้งหมดผ่าน ไม่พบข้อผิดพลาดเมื่อมีการตรวจสอบแพ็คเกจเพื่อสร้างใน rstudio หรือใช้ devtools :: check () นั่นหมายความว่าแพ็คเกจสามารถส่งไปยัง CRAN ได้โดยไม่มีปัญหาใด ๆ (ยกเว้นเพื่อโน้มน้าวใจว่าแพ็คเกจนั้นเกี่ยวข้อง)!
การรวมอย่างต่อเนื่องหมายความว่าผลของรหัสที่เปลี่ยนแปลงหลังจากอัปโหลดไปยัง GitHub จะแสดงโดยอัตโนมัติหลังจากระยะเวลาสั้น ๆ กล่าวอีกนัยหนึ่ง: หากแพ็คเกจไม่สามารถสร้างได้อีกต่อไปโดยข้อบกพร่องที่แนะนำ (ตัวอย่างเช่นการทดสอบที่ล้มเหลวในขณะนี้) มันจะถูกสังเกตก่อน หรือถ้ามีคนอื่นหยุดมันทีมจะสังเกตเห็นก่อน นอกจากนี้เมื่อมีคนส่งคำขอดึงเราสามารถดูได้ว่ามันจะทำลายการสร้างแพ็คเกจก่อนที่จะยอมรับหรือไม่
มีบริการบูรณาการอย่างต่อเนื่องอื่น ๆ อีกมากมายที่ใช้งานได้เช่น Jenkins, Codeship, Circleci และ Wercker ฉันเพิ่งเกิดขึ้นเพื่อเรียนรู้ Travis CI ก่อน
รูปที่ 2. โลโก้ Travis CI
ขั้นตอนแรกของการตั้งค่าของเราคือการเปิดใช้งาน Travis CI
Travis CI เป็นบริการบูรณาการอย่างต่อเนื่อง (ดังนั้น 'CI' ในชื่อ) ที่ใช้งานได้ฟรีเมื่อพัฒนาซอฟต์แวร์ FOLS และทำงานได้ดีกับ GitHub
ก่อนอื่นมาเปิดใช้งาน Travis CI เพราะเฉพาะเมื่อเปิดใช้งานจะเริ่มทำงานเมื่ออัปโหลดไปยัง GitHub
หากต้องการทำสิ่งนี้: ไปที่เว็บไซต์ Travis CI, www.travis-ci.org และลงชื่อเข้าใช้ด้วยบัญชี GitHub เทรวิสขออนุญาตให้ใช้ข้อมูล GitHub เช่นชื่อผู้ใช้และอีเมล หลังจากการอนุญาต Travis CI แสดงที่เก็บ GitHub ของผู้ใช้ทั้งหมดและสถานะการเปิดใช้งานของพวกเขา:
รูปที่ 3 ภาพรวมของ GitHubs ที่ตรวจสอบโดย Travis CI
ในรูปนี้ผู้ใช้จะแสดงว่ามีที่เก็บ GitHub อย่างน้อยสามแห่งซึ่งไม่เปิดใช้งาน (Cross สีเทา) และอีกสองรายการคือ (การตรวจสอบสีเขียว)
ไปค้นหา GitHub ของแพ็คเกจ R และเปิดใช้งาน
การครอบคลุมรหัสเป็นเปอร์เซ็นต์ของบรรทัดของรหัสที่ครอบคลุมโดยการทดสอบ หากมีการตรวจพบบรรทัดที่ไม่ผ่านการตรวจพบรหัสที่ตายแล้ว (ที่สามารถลบออกได้) หรือการทดสอบควรเป็นคำเขียนที่ใช้ประโยชน์จากรหัสนั้น ความครอบคลุมของรหัสมีความสัมพันธ์กับคุณภาพของรหัส [Del Frate et al., 1995]
มีบริการอื่น ๆ ที่ครอบคลุมรหัสการติดตามเช่น Code Imlimate, Codacity, CoverAlls, QuantifiedCode และอื่น ๆ อีกมากมาย มันเกิดขึ้นได้ว่าแพ็คเกจที่เราจะใช้ ('lintr') ใช้ codecov
รูปที่ 4. โลโก้ codecov
ขั้นตอนที่สองคือการเปิดใช้งาน codecov
Codecov เป็นเว็บไซต์ที่แสดงความครอบคลุมรหัสของ GitHub ที่เก็บในรูปแบบที่ใช้งานง่าย Codecov ติดตามการครอบคลุมรหัสของโครงการตลอดเวลา หากมีหลายกิ่งก้านการครอบคลุมรหัสจะแสดงแยกต่างหากสำหรับแต่ละสาขา
เราจำเป็นต้องเปิดใช้งาน Codecov ตอนนี้เพราะ
Codecov จะได้รับและแสดงความครอบคลุมรหัสของผู้ใช้ที่ลงทะเบียนเท่านั้น
หากต้องการเปิดใช้งาน Codecov ให้ไปที่เว็บไซต์ https://codecov.io และลงชื่อเข้าใช้ด้วยบัญชี GitHub มันจะขอการอนุญาตสำหรับข้อมูล GitHub บางอย่างเช่นชื่อผู้ใช้และอีเมล
หลังจากได้รับอนุญาตแล้ว Codecov จะแสดงความครอบคลุมรหัสของ GitHubs ของผู้ใช้ทั้งหมด สำหรับผู้ใช้ใหม่หน้าจอนี้ส่วนใหญ่จะว่างเปล่าเนื่องจากไม่มีการวัดความครอบคลุมของรหัส สำหรับผู้ใช้ที่มีการวัดความครอบคลุมของรหัสที่เก็บข้อมูลของ GitHub หลายรายการหน้าจอ Codecov จะมีลักษณะเช่นนี้:
รูปที่ 5: ตัวอย่างภาพรวมของ githubs ที่ตรวจสอบโดย codecov
ในรูปนี้เราสามารถเห็นการใช้งานที่มีที่เก็บ GitHub อย่างน้อยสามแห่งที่มีการตรวจสอบความครอบคลุมของรหัส
ขั้นตอนที่สามคือการสอนเทรวิส CI ว่าจะทำอย่างไรเมื่ออัปโหลดรหัสใหม่ไปยัง GitHub ที่เปิดใช้งาน
เทรวิสได้รับคำแนะนำว่าจะทำอย่างไรโดยใช้สคริปต์บิลด์ซึ่งเป็นไฟล์ข้อความธรรมดาชื่อ . travis.yml ชื่อไฟล์เริ่มต้นด้วยจุดซึ่งทำให้เป็นไฟล์ที่ซ่อนอยู่ในระบบ UNIX ส่วนขยาย '.yml' เป็นตัวย่อของ 'ภาษามาร์กอัพอื่น' Travis CI ได้รับคำแนะนำในภาษาคำสั่งทุบตี
ในโฟลเดอร์รูทของโครงการสร้างไฟล์ชื่อ . 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_GITHUB_PACKAGES' สั่งให้ Travis CI ติดตั้งแพ็คเกจ GitHub ที่โฮสต์เหล่านี้ ส่วน 'after_success' ทำงานหลังจากแพ็คเกจผ่าน การตรวจสอบ Devtools :: () ในส่วนนี้มันจะเรียกใช้การตรวจสอบจากแพ็คเกจ 'LINTR', 'COVR' และ 'GoodPractice' เพิ่มเติมเกี่ยวกับแพ็คเกจเหล่านั้นในภายหลัง
หลังจากสร้างไฟล์ . travis.yml นี้ให้อัปโหลดไปยัง GitHub
หลังจากอัปโหลด . travis.yml ไปยัง gitHub มันจะปรากฏขึ้นทันทีบน gitHub:
รูปที่ 6. 'prde' gitHub หลังจากเพิ่มสคริปต์การสร้าง Travis CI
การผลักดันไปยัง GitHub ทำให้เกิด Travis CI และมันจะเริ่มทำงานทันที
Travis CI ต้องการเวลาในการตั้งค่าเครื่องเสมือน ทุกครั้งที่มีการอัปโหลดไปยัง GitHub เครื่องเสมือนจะถูกสร้างขึ้นเพื่อให้แน่ใจว่าสภาพแวดล้อมการสร้างและทดสอบที่ทำซ้ำได้
หากต้องการดู Travis CI ทำงานให้กลับไปที่เว็บไซต์ Travis CI, https://travis-ci.org หลังจากประมาณหนึ่งนาทีความคืบหน้าของเทรวิสซีไอจะปรากฏให้เห็น 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 ความคิดเห็นโดย Lintr-bot ในการกระทำดังที่แสดงใน gitHub
Lintr-bot นั้นถูกต้องเสมอ หากจำเป็น 'LINTR' สามารถทำได้เพื่อให้ได้มาตรฐานการเข้ารหัสอื่น ๆ
รูปที่ 12. โลโก้ Mangothecat
การย้ายจาก Lintr-bots Words of Wisdom เราจะขยายข้อเสนอแนะจากแพ็คเกจ 'GoodPractice' (โดย MangotheCat) อันนี้แสดง:
รูปที่ 13. ข้อเสนอแนะที่ได้รับจากแพ็คเกจ 'GoodPractice'
'GoodPractice' ขยาย 'lintr' โดยการเพิ่มแนวทางปฏิบัติที่ดี ตัวอย่างเช่นอาจแนะนำให้ไม่ใช้ฟังก์ชั่นเฉพาะ แต่ต้องใช้ทางเลือกที่ดีกว่าแทน
มีสามเหลี่ยมที่สามที่สามารถขยายได้โดยให้ข้อมูลเกี่ยวกับการโทรไปยังแพ็คเกจ 'COVR' ในบันทึกการสร้างเทรวิส การดูข้อมูลนี้ที่นี่ไม่เป็นประโยชน์เนื่องจากจะแสดงในรูปแบบดิบ กลับไปที่เว็บไซต์ codecov แทน https://codecov.io เพื่อดูการครอบคลุมรหัสในแบบที่สวยกว่า:
รูปที่ 14. ข้อเสนอแนะที่ได้รับจากแพ็คเกจ 'COVR' ตามที่แสดงโดย codecov
ความครอบคลุมของรหัสแสดงให้เห็นว่าผู้เขียนแพ็คเกจ 'PRDE' ลืมที่จะทดสอบว่าฟังก์ชั่น do_magic จะโยนข้อยกเว้นอย่างแน่นอนเมื่ออินพุตไม่ใช่ตัวเลข
ต้องขอบคุณเครื่องมือเหล่านี้ (และผู้คนที่เขียนสิ่งเหล่านั้น) มันง่ายกว่าที่จะกลายเป็นโปรแกรมเมอร์ R ที่ดีขึ้น
ฉันแนะนำให้ฟังคำแนะนำเหล่านี้และทำตามสิ่งเหล่านี้
หากมีใครไม่เห็นด้วยกับคำแนะนำของผู้เชี่ยวชาญฉันมักจะอยากรู้ว่าทำไม ผู้เชี่ยวชาญได้เลือกมาตรฐานเหล่านั้นด้วยเหตุผล และผู้เชี่ยวชาญเหล่านั้นก็ตระหนักถึงข้อโต้แย้งที่สนับสนุนมาตรฐานอื่น ๆ
สำหรับนักเรียนของฉันฉันบังคับใช้บันทึก 'Oclint' และ 'GoodPractice' ที่สะอาดและครอบคลุมรหัสอย่างน้อย 95%
ทุกคนสามารถใช้เทคนิคเหล่านี้ตั้งแต่เริ่มต้นจนถึงโปรแกรมเมอร์ที่มีประสบการณ์ สำหรับการพัฒนาไหมขัดฟัน, GitHub, Travis CI และ Codecov นั้นฟรี
Code better. Sleep better. [Langr, 2013]
เมื่อมีการล้างการทดสอบทั้งหมดและครอบคลุมรหัสสูงสิ่งนี้อาจแสดงต่อโลก สิ่งนี้สามารถทำได้โดยการเพิ่ม Build Badges ลงในไฟล์ readme.md ในโฟลเดอร์หลักของ GitHub ป้ายดังกล่าวมีลักษณะเช่นนี้:
รูปที่ 15. ป้ายที่แสดงบน 'prde' gitHub
ในการแสดงป้ายเหล่านี้ให้เพิ่มรหัสต่อไปนี้ลงใน readme.md ในโฟลเดอร์หลักของ GitHub:
[](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
