By มาร์ซิน ดูเบล, แอพซิลอน

Clean R Code เป็นสิ่งสำคัญ

 
 
ด้วยประสบการณ์หลายปีในการส่งมอบโครงการที่ประสบความสำเร็จ ฉันพบองค์ประกอบหนึ่งเดียวในการนำไปใช้งานแต่ละครั้ง ฐานรหัสที่สะอาด อ่านได้ และกระชับเป็นกุญแจสำคัญในการทำงานร่วมกันอย่างมีประสิทธิภาพและมอบคุณค่าคุณภาพสูงสุดให้กับลูกค้า

การตรวจสอบโค้ดเป็นส่วนสำคัญของการรักษากระบวนการโค้ดคุณภาพสูง นอกจากนี้ยังเป็นวิธีที่ยอดเยี่ยมในการแบ่งปันแนวทางปฏิบัติที่ดีที่สุดและแจกจ่ายความรู้ให้กับสมาชิกในทีม ที่ Appsilon เราถือว่าการตรวจสอบโค้ดเป็นสิ่งจำเป็นสำหรับทุกโครงการ อ่านเพิ่มเติมเกี่ยวกับวิธีการจัดระเบียบงานของเราใน โพสต์บล็อกของ Olga เกี่ยวกับแนวทางปฏิบัติที่ดีที่สุดที่แนะนำสำหรับทีมวิทยาศาสตร์ข้อมูลทั้งหมด

การมีกระบวนการตรวจสอบโค้ดที่เป็นที่ยอมรับไม่ได้เปลี่ยนความจริงที่ว่านักพัฒนามีหน้าที่รับผิดชอบในการเขียนโค้ดที่ดีและสะอาด! การชี้ให้เห็นข้อผิดพลาดพื้นฐานทั้งหมดของโค้ดเป็นเรื่องที่เจ็บปวด ใช้เวลานาน และทำให้ผู้ตรวจสอบหันเหความสนใจจากการลงลึกในตรรกะของโค้ดหรือปรับปรุงประสิทธิภาพของโค้ด

โค้ดที่เขียนไม่ดีอาจส่งผลเสียต่อขวัญกำลังใจของทีมได้เช่นกัน ผู้ตรวจสอบโค้ดรู้สึกหงุดหงิด ในขณะที่ผู้สร้างโค้ดอาจรู้สึกขุ่นเคืองจากความคิดเห็นจำนวนมาก นั่นคือเหตุผลที่ก่อนที่จะส่งโค้ดไปตรวจสอบ นักพัฒนาจำเป็นต้องตรวจสอบให้แน่ใจว่าโค้ดนั้นสะอาดที่สุด นอกจากนี้ โปรดทราบว่าไม่มีผู้ตรวจสอบโค้ดที่สามารถช่วยเหลือได้เสมอไป บางครั้งคุณอยู่คนเดียวในโครงการ แม้ว่าคุณคิดว่าโค้ดนี้ใช้ได้สำหรับคุณในตอนนี้ แต่ให้ลองอ่านซ้ำในอีกสองสามเดือน - คุณต้องการให้ชัดเจนเพื่อหลีกเลี่ยงการเสียเวลาของคุณเองในภายหลัง

ในบทความนี้ ผมสรุปข้อผิดพลาดที่พบบ่อยที่สุดที่ควรหลีกเลี่ยงและสรุปแนวทางปฏิบัติที่ดีที่สุดที่ควรปฏิบัติตามในการเขียนโปรแกรมโดยทั่วไป ปฏิบัติตามคำแนะนำเหล่านี้เพื่อเพิ่มความเร็วในกระบวนการทบทวนโค้ดซ้ำๆ และเป็นนักพัฒนา Rockstar ในสายตาของผู้ตรวจทานของคุณ!

หลีกเลี่ยงความคิดเห็นที่มีความคิดเห็น

 
 
การเพิ่มความคิดเห็นลงในโค้ดถือเป็นทักษะที่สำคัญสำหรับนักพัฒนา อย่างไรก็ตาม ทักษะที่สำคัญกว่าและยากกว่าที่จะเชี่ยวชาญคือการรู้ว่าเมื่อใด ไม่ เพื่อเพิ่มความคิดเห็น การเขียนความคิดเห็นที่ดีเป็นศิลปะมากกว่าวิทยาศาสตร์ ต้องใช้ประสบการณ์อย่างมาก และคุณสามารถเขียนบทเกี่ยวกับหนังสือทั้งบทได้ (เช่น  โปรดคลิกที่นี่เพื่ออ่านรายละเอียดเพิ่มเติม). 

มีกฎง่ายๆ สองสามข้อที่คุณควรปฏิบัติตามเพื่อหลีกเลี่ยงความคิดเห็นเกี่ยวกับความคิดเห็นของคุณ:

• ความคิดเห็นควรเพิ่มความรู้ภายนอกให้กับผู้อ่าน: หากพวกเขากำลังอธิบายสิ่งที่เกิดขึ้นในตัวโค้ดเอง แสดงว่าโค้ดไม่สะอาดและจำเป็นต้องปรับโครงสร้างใหม่ หากมีการใช้แฮ็ค ความคิดเห็นก็อาจใช้เพื่ออธิบายสิ่งที่เกิดขึ้น ความคิดเห็นจำเป็นต้องมีตรรกะทางธุรกิจหรือข้อยกเว้นที่เพิ่มตามวัตถุประสงค์ พยายามนึกถึงสิ่งที่อาจทำให้ผู้อ่านประหลาดใจในอนาคตและหลีกเลี่ยงความสับสน
• เขียนความคิดเห็นที่สำคัญเท่านั้น! ความคิดเห็นของคุณไม่ควรเป็นพจนานุกรมของข้อมูลที่ค้นหาได้ง่าย โดยทั่วไป ความคิดเห็นจะทำให้เสียสมาธิและไม่ได้อธิบายตรรกะเช่นเดียวกับโค้ด ตัวอย่างเช่น เมื่อเร็ว ๆ นี้ ฉันเพิ่งเห็นความคิดเห็นเช่นนี้ในรหัส: trimws(.) # this function trims leading/trailing white spaces - ซึ่งเป็นที่ซ้ำซากจำเจ หากผู้อ่านไม่รู้ว่าทำหน้าที่อะไร trimws ก็ทำได้ง่ายๆ สามารถตรวจสอบได้ ความคิดเห็นที่แข็งแกร่งกว่านี้อาจมีประโยชน์ เช่น: trimws(.) # TODO(Marcin Dubel): Trimming white spaces is crucial here due to database entries inconsistency; data needs to be cleaned.
• เมื่อเขียนฟังก์ชันใน R ผมขอแนะนำ ใช้ {roxygen2} ความคิดเห็น แม้ว่าคุณจะไม่ได้เขียนแพ็คเกจก็ตาม เป็นเครื่องมือที่ยอดเยี่ยมสำหรับการจัดระเบียบความรู้เกี่ยวกับเป้าหมายการทำงาน พารามิเตอร์ และผลลัพธ์
• เขียนความคิดเห็นเท่านั้น (รวมถึงทุกส่วนของโค้ด) เป็นภาษาอังกฤษ การทำให้ผู้อ่านทุกคนเข้าใจได้อาจช่วยประหยัดปัญหาการเข้ารหัสที่อาจปรากฏขึ้นหากคุณใช้อักขระพิเศษจากภาษาแม่ของคุณ
• ในกรณีที่จำเป็นต้องปรับโครงสร้าง/แก้ไขโค้ดบางส่วนในอนาคต ให้ทำเครื่องหมายด้วย # TODO ความคิดเห็น นอกจากนี้ ให้เพิ่มข้อมูลเพื่อระบุว่าคุณเป็นผู้เขียนความคิดเห็นนี้ (หากต้องการติดต่อในกรณีที่จำเป็นต้องมีรายละเอียด) และคำอธิบายสั้น ๆ ว่าเหตุใดรหัสต่อไปนี้จึงถูกทำเครื่องหมายเป็นสิ่งที่ต้องทำและไม่ได้แก้ไขในทันที
• อย่าปล่อยให้รหัสแสดงความคิดเห็นไม่มีความคิดเห็น! ไม่เป็นไรที่จะเก็บบางส่วนไว้สำหรับอนาคตหรือปิดไว้ชั่วขณะหนึ่ง แต่ให้ทำเครื่องหมายเหตุผลสำหรับการกระทำนี้เสมอ

โปรดจำไว้ว่าความคิดเห็นจะอยู่ในรหัส หากมีบางสิ่งที่คุณต้องการบอกผู้รีวิวของคุณ แต่เพียงครั้งเดียว ให้เพิ่มความคิดเห็นในคำขอ Pull (Merge) ไม่ใช่ในโค้ด

ตัวอย่าง: ฉันเพิ่งเห็นการลบโค้ดบางส่วนที่มีความคิดเห็นเช่น: “ถูกลบเมื่อตรรกะเปลี่ยนไป” โอเค ยินดีที่ได้รู้ แต่ภายหลังความคิดเห็นในโค้ดนั้นดูแปลกและซ้ำซาก เนื่องจากผู้อ่านจะไม่เห็นโค้ดที่นำออกไปแล้ว

Strings

 
 
ปัญหาทั่วไปที่เกี่ยวข้องกับข้อความคือความสามารถในการอ่านการต่อสตริง สิ่งที่ฉันพบมากคือการใช้มากเกินไปของ paste การทำงาน. อย่าเข้าใจฉันผิด มันเป็นฟังก์ชั่นที่ยอดเยี่ยมเมื่อสตริงของคุณเรียบง่ายเช่น paste("My name is", my_name)แต่สำหรับรูปแบบที่ซับซ้อนกว่านั้น อ่านยาก: 

paste("My name is", my_name, "and I live in", my_city, "developing in", language, "for over", years_of_coding)

ทางออกที่ดีกว่าคือการใช้ sprintf ฟังก์ชั่นหรือ glue, เช่น 

glue(“My name is {my_name} and I live in {my_city} developing in {language} for over {years_of_coding}”)

ชัดเจนกว่านี้ถ้าไม่มีเครื่องหมายจุลภาคและเครื่องหมายคำพูดทั้งหมดหรือไม่

เมื่อต้องจัดการกับบล็อคโค้ดจำนวนมาก จะเป็นการดีที่จะแยกพวกมันไปยังตำแหน่งที่แยกจากกัน เช่น ไปที่a .yml ไฟล์. ทำให้ทั้งโค้ดและบล็อกข้อความอ่านและบำรุงรักษาได้ง่ายขึ้น

เคล็ดลับสุดท้ายที่เกี่ยวข้องกับข้อความ: หนึ่งในเทคนิคการดีบักซึ่งมักใช้ในแอปพลิเคชัน Shiny กำลังเพิ่ม print() งบ. ตรวจสอบอีกครั้งว่าไม่มีงานพิมพ์เหลืออยู่ในโค้ดหรือไม่ - นี่อาจเป็นเรื่องที่น่าอายในระหว่างการตรวจทานโค้ด!

ลูป

 
 
ลูปเป็นหนึ่งในหน่วยการสร้างการเขียนโปรแกรมและเป็นเครื่องมือที่ทรงพลังมาก อย่างไรก็ตาม มันสามารถคำนวณได้หนัก ดังนั้นต้องใช้อย่างระมัดระวัง กฎทั่วไปที่คุณควรปฏิบัติตามคือ: ตรวจสอบอีกครั้งเสมอว่าการวนซ้ำเป็นตัวเลือกที่ดีหรือไม่ แทบจะไม่เป็นกรณีที่คุณต้องวนซ้ำแถวใน data.frame: น่าจะมี {dplyr} ทำหน้าที่จัดการกับปัญหาได้อย่างมีประสิทธิภาพมากขึ้น 

แหล่งที่มาทั่วไปของปัญหาอื่นคือการวนซ้ำองค์ประกอบโดยใช้ความยาวของวัตถุ เช่น for(i in 1:length(x)) .... แต่ถ้าความยาวของ x เป็นศูนย์ล่ะ! ใช่ การวนซ้ำจะไปในทางอื่นสำหรับค่าตัววนซ้ำ 1, 0 นั่นอาจไม่ใช่แผนของคุณ โดยใช้ seq_along or seq_len ฟังก์ชั่นมีความปลอดภัยมากขึ้น

ยังจำเกี่ยวกับ apply ตระกูลของฟังก์ชันสำหรับการวนซ้ำ พวกเขายอดเยี่ยม (ไม่ต้องพูดถึง {purrr} โซลูชั่น)! โปรดทราบว่าการใช้ sapply อาจถูกวิจารณ์โดยผู้ตรวจทานว่าไม่เสถียร – เพราะฟังก์ชันนี้จะเลือกประเภทของผลลัพธ์เอง! ดังนั้นบางครั้งมันจะเป็นรายการ บางครั้งเวกเตอร์ โดยใช้ vapply ปลอดภัยกว่าเนื่องจากโปรแกรมเมอร์กำหนดคลาสเอาต์พุตที่คาดหวัง

การแชร์รหัส

 
 
แม้ว่าคุณจะทำงานคนเดียว คุณอาจต้องการให้โปรแกรมของคุณทำงานอย่างถูกต้องบนเครื่องอื่น และมันสำคัญแค่ไหนเมื่อคุณแบ่งปันรหัสกับทีม! เพื่อให้บรรลุสิ่งนี้ อย่าใช้เส้นทางที่แน่นอนในโค้ดของคุณ เช่น “/home/marcin/my_files/old_projects/september/project_name/file.txt” คนอื่นจะไม่สามารถเข้าถึงได้ โปรดทราบว่าการละเมิดโครงสร้างโฟลเดอร์จะทำให้โค้ดขัดข้อง 

เนื่องจากคุณควรมีโครงการสำหรับงานเขียนโค้ดทั้งหมดอยู่แล้ว คุณจึงจำเป็นต้องใช้เส้นทางที่เกี่ยวข้องกับโครงการนั้นๆ ในกรณีนี้ มันจะเป็น “./file.txt” ยิ่งไปกว่านั้น ฉันขอแนะนำให้เก็บพาธทั้งหมดเป็นตัวแปรไว้ในที่เดียว ดังนั้นการเปลี่ยนชื่อไฟล์จำเป็นต้องเปลี่ยนโค้ดเพียงครั้งเดียว ไม่ใช่ เช่น ไฟล์ที่แตกต่างกันยี่สิบในหกไฟล์

บางครั้งซอฟต์แวร์ของคุณจำเป็นต้องใช้ข้อมูลประจำตัวหรือโทเค็นบางอย่าง เช่น กับฐานข้อมูลหรือที่เก็บส่วนตัว คุณไม่ควรเปิดเผยความลับดังกล่าวกับที่เก็บ! แม้ว่าผลงานจะเหมือนกันระหว่างทีมก็ตาม โดยปกติ แนวปฏิบัติที่ดีคือการรักษาค่านิยมดังกล่าวไว้ใน .Renviron file เป็นตัวแปรสภาพแวดล้อมที่โหลดเมื่อเริ่มต้นและตัวไฟล์เองจะถูกละเว้นใน repo คุณสามารถอ่านเพิ่มเติมเกี่ยวกับเรื่องนี้  โปรดคลิกที่นี่เพื่ออ่านรายละเอียดเพิ่มเติม.

แนวปฏิบัติด้านการเขียนโปรแกรมที่ดี

 
 
สุดท้าย มาเน้นที่วิธีปรับปรุงโค้ดของคุณ อย่างแรกเลย รหัสของคุณควรเข้าใจได้ง่ายและสะอาด แม้คุณจะทำงานคนเดียว แต่เมื่อกลับมาใช้โค้ดอีกครั้งหลังจากนั้น จะทำให้ชีวิตของคุณง่ายขึ้น! 

ใช้ชื่อตัวแปรเฉพาะ แม้ว่าจะดูยาว กฎทั่วไปก็คือ คุณควรจะสามารถเดาได้ว่าอะไรอยู่ข้างในเพียงแค่อ่านชื่อ ดังนั้น table_cases_per_country ไม่เป็นไร แต่ tbl1 ไม่ใช่. หลีกเลี่ยงคำย่อ ยาวจะดีกว่าที่จะคลุมเครือ รักษารูปแบบที่สอดคล้องกันสำหรับชื่อวัตถุ (เช่น camelCase หรือ snake_case) ที่ตกลงกันในหมู่สมาชิกในทีม 

อย่าย่อค่าตรรกะ T for  TRUE และ  F for  FALSE – รหัสจะใช้งานได้ แต่ T และ  F เป็นวัตถุปกติที่สามารถเขียนทับได้ในขณะที่ TRUE และ  FALSE เป็นค่านิยมพิเศษ 

อย่าเปรียบเทียบค่าตรรกะโดยใช้สมการ เช่น if(my_logical == TRUE). ถ้าเปรียบได้กับ TRUEหมายความว่าค่าของคุณมีเหตุผลอยู่แล้ว ดังนั้น if(my_logical) ก็เพียงพอแล้ว! หากคุณต้องการตรวจสอบอีกครั้งว่าค่าเป็น TRUE แน่นอน (และไม่ใช่เช่น NA) คุณสามารถใช้ isTRUE() ฟังก์ชัน

ตรวจสอบให้แน่ใจว่าคำสั่งตรรกะของคุณถูกต้อง ตรวจสอบว่าคุณเข้าใจความแตกต่างของ R ระหว่าง ตัวดำเนินการตรรกะเดี่ยวและคู่!

ระยะห่างที่ดีมีความสำคัญต่อความสามารถในการอ่าน ตรวจสอบให้แน่ใจว่ากฎเหมือนกันและตกลงกันในทีม จะทำให้ง่ายต่อการติดตามโค้ดของกันและกัน ทางออกที่ง่ายที่สุดคือการยืนบนไหล่ของยักษ์และปฏิบัติตาม คู่มือสไตล์ tidyverse. 

อย่างไรก็ตาม การตรวจสอบสไตล์ในทุกบรรทัดระหว่างการตรวจทานนั้นค่อนข้างจะไร้ประสิทธิภาพ ดังนั้นแนะนำให้แนะนำ linter และ  จัดแต่งทรงผม ในเวิร์กโฟลว์การพัฒนาของคุณ ดังที่นำเสนอใน โพสต์บล็อกของ Olga. สิ่งนี้สามารถช่วยชีวิตได้! เมื่อเร็ว ๆ นี้เราพบข้อผิดพลาดในรหัสดั้งเดิมบางตัวที่ linter รู้จักโดยอัตโนมัติ:

sum_of_values <- first_element + second_element

สิ่งนี้จะไม่ส่งคืนผลรวมขององค์ประกอบตามที่ผู้เขียนคาดหวัง

การพูดชื่อตัวแปร – เป็นที่รู้จักกันว่าเป็นหนึ่งในสิ่งที่ยากที่สุดในการเขียนโปรแกรม จึงหลีกเลี่ยงเมื่อไม่จำเป็น โปรดทราบว่าฟังก์ชัน R จะคืนค่าองค์ประกอบที่สร้างขึ้นล่าสุดตามค่าเริ่มต้น ดังนั้นคุณจึงสามารถแทนที่ได้อย่างง่ายดาย:

sum_elements <- function(first, second) { my_redundant_variable_name <- sum(first, second) return(my_redundant_variable_name)
}

ด้วยสิ่งที่สั้นกว่า (และง่ายกว่านี้ คุณไม่จำเป็นต้องนึกถึงชื่อ):

sum_elements <- function(first, second) { sum(first, second)
}

ในทางกลับกัน โปรดใช้ตัวแปรเพิ่มเติมทุกครั้งที่คุณเรียกใช้ฟังก์ชันหรือการคำนวณซ้ำ! มันจะทำให้การคำนวณมีประสิทธิภาพมากขึ้นและง่ายต่อการแก้ไขในอนาคต อย่าลืมเก็บรหัสของคุณ แห้ง – อย่าทำซ้ำตัวเอง. หากคุณคัดลอกและวางโค้ด ให้คิดให้รอบคอบว่าไม่ควรบันทึกโค้ดลงในตัวแปร ทำในลูป หรือย้ายไปที่ฟังก์ชัน 

สรุป

 
 
และคุณมีมัน – ห้ากลยุทธ์ในการเขียนโค้ด R ที่สะอาดและปล่อยให้ผู้ตรวจสอบโค้ดของคุณไม่มีความคิดเห็น ห้าสิ่งนี้เพียงอย่างเดียวจะช่วยให้มั่นใจว่าคุณกำลังเขียนโค้ดคุณภาพเยี่ยมที่เข้าใจง่าย แม้กระทั่งหลายปีที่ผ่านไป มีความสุขในการเข้ารหัส!

 
Bio: มาร์ซิน ดูเบล เป็นวิศวกรที่ Appsilon

Original. โพสต์ใหม่โดยได้รับอนุญาต

ที่เกี่ยวข้อง

• รองรับเครื่องเวกเตอร์สำหรับการรู้จำตัวอักษรที่เขียนด้วยมือใน R
• ภาษาการเขียนโปรแกรมยอดนิยมและการใช้งาน
• คู่มือเกี่ยวกับวิธีการเป็นนักวิทยาศาสตร์ข้อมูล (วิธีการทีละขั้นตอน)