มาตรฐานการเข้ารหัสเพื่อความชัดเจน: แสดงความคิดเห็นทุกบรรทัดของรหัส?

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

ฉันให้คะแนนรหัสนักเรียนที่ไม่มีความคิดเห็นและเห็นว่าเพราะเหตุใดพวกเขาจึงควรทำเครื่องหมายเพราะละเลยพวกเขา

ฉันเข้าใจว่าการใช้ชื่อที่ดีโครงสร้างที่เรียบง่ายฟังก์ชั่นสั้น ๆ และโมดูลที่มุ่งเน้นจะทำให้โค้ดนั้นเข้าใจได้ง่ายพอที่จะลดความคิดเห็นได้

ฉันยังเข้าใจด้วยว่าความคิดเห็นควรอธิบายว่าทำไมรหัสทำในสิ่งที่มันทำไม่ได้อย่างไร

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

ตัวอย่างประเภทของรหัสกฎนี้อาจต้องใช้เมื่อถือว่าเป็นบรรทัดในรายการตรวจสอบ:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

หากเป็นไปได้ที่จะแสดงสิ่งนี้อย่างถูกต้องในเอกสารมาตรฐานและอาจไม่เป็นเช่นนั้นฉันต้องการรวบรวมแนวคิดตามบรรทัดเหล่านี้:

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

คำตอบของ Michael Durrant นั้น IMHO ไม่เลว แต่จริงๆแล้วมันไม่ได้ตอบคำถาม (ตามที่เขายอมรับ) ดังนั้นฉันจะพยายามให้คำตอบซึ่ง:

ฉันยังเข้าใจด้วยว่าความคิดเห็นควรอธิบายว่าทำไมรหัสทำในสิ่งที่มันทำไม่ได้อย่างไร

ให้ทั้งหมดนี้เป็นไปได้ที่จะเขียนมาตรฐานการเข้ารหัสที่ดีที่จับความคิดนี้

เห็นได้ชัดว่าคุณสามารถเขียนรายการตรวจสอบสำหรับความคิดเห็นรหัสของคุณที่มีคำถามเช่น

• "ถ้ามีความคิดเห็นอธิบายว่าทำไมโค้ดถึงทำในสิ่งที่มันทำ?"
• "คือแต่ละบรรทัดของรหัส - ในบริบท - ทั้งอธิบายตัวเองมากพอที่ไม่จำเป็นต้องแสดงความคิดเห็นหรือไม่ถ้ามันมาพร้อมกับความคิดเห็นที่ปิดช่องว่างที่หรือไม่ (ควร) รหัสสามารถเปลี่ยนได้ดังนั้น ไม่ต้องการความคิดเห็นอีกแล้วเหรอ? "

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

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

การต่อต้านรูปแบบหลักนำไปสู่รหัสคุณภาพต่ำโดยมีความชัดเจนน้อยลง

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

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

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

พิจารณา:

living_room_set = tables + chairs.

พิจารณาตอนนี้:

set = tbls+chrs # Make the set equal to the table plus the chairs

คุณไม่เพียง แต่มีชื่อที่เป็นความลับมากขึ้นและอ่านได้มากขึ้นเท่านั้นคุณยังต้องมองย้อนกลับไปดูโค้ดแล้วชุดอะไร ดูที่ด้านซ้ายของรหัส, มองไปที่ความคิดเห็น, tbls คืออะไร, มองไปทางซ้ายที่โค้ด, มองไปที่ความคิดเห็น, อะไรคือ chrs, มองไปที่ความคิดเห็นที่ถูกต้อง Yuch!

สรุป

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

• รหัสและความคิดเห็นไม่ซิงค์กันเมื่อมีการเปลี่ยนแปลงเพียงอันเดียว

• ความคิดเห็นอาจอธิบายสิ่งที่คนคนหนึ่งคิด แต่อาจผิดและปกปิดข้อบกพร่อง

• รหัสอ่านยากขึ้น

• รหัสที่ดีกลายเป็นเรื่องยากที่จะเขียน

• มีแนวโน้มที่จะใช้ชื่อลับ ๆ มากกว่านี้

• อักขระมากเกินไปที่จะอ่านในรหัสและความคิดเห็น

• บรรณาธิการที่แตกต่างกันใช้สไตล์ที่ต่างกัน

• ต้องการความรู้ภาษาอังกฤษสูงกว่าการเขียนโปรแกรม

• ใช้เวลาและทรัพยากรและการลบออกจากค่าระยะยาว *

บวกเถียงรหัสที่ดีกว่าโดยไม่มีความคิดเห็นเช่น - ในความเป็นจริงมีมาตรฐาน (!) - ชื่อตัวแปรทั้งหมดจะต้องเป็น full_english_words - มีอยู่หนึ่งรายการ! ดังนั้นใช้พลังงาน 'มาตรฐาน' ที่มีต่อมาตรฐานของรหัสที่เป็นลายลักษณ์อักษรและการทดสอบ

หนึ่งในสองปัญหาที่ยากคือการตั้งชื่อ - อย่าข้ามปัญหากับความคิดเห็น

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

* รหัสในวันพรุ่งนี้

ฉันไม่คิดว่าเอกสารมาตรฐานการเข้ารหัสเป็นที่ที่ระบุสามัญสำนึกอยู่แล้ว จุดประสงค์ของมาตรฐานการเข้ารหัสคือเพื่อรับประกันความมั่นคง (และหลีกเลี่ยงการขัดแย้ง) เกี่ยวกับปัญหาที่คนที่มีเหตุผลอาจไม่เห็นด้วยและไม่มีคำตอบที่ชัดเจนเพียงคำเดียวเช่นการตั้งชื่อการประชุมการเยื้องเป็นต้น

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

หากคุณเริ่มเพิ่ม "แนวทางปฏิบัติที่ดีที่สุด" ทุกชนิดลงในมาตรฐานการเข้ารหัสคุณจะสิ้นสุดการทำซ้ำซึ่งได้ระบุไว้ในหนังสือหลายเล่มแล้ว เพียงแค่ซื้อ "Clean Code", "Code Complete" และ "The Pragmatic Programmer" ให้กับผู้พัฒนาที่มีปัญหาและรักษามาตรฐานการเข้ารหัสของคุณไว้

มันเป็นไปไม่ได้. สิ่งที่คุณกำลังพยายามทำคือการสร้างกลไกการตัดสินที่ดี

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

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

ปรับปรุง

การตอบสนองของฉันในคำพูดสำหรับการเน้น:

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

ปัญหานี่คือมาตรฐานการเข้ารหัสเป็นเพียงที่เป็นมาตรฐาน มากความคิดอัตนัยควรไม่อยู่ในมาตรฐานการเข้ารหัส อาจเป็นแนวทางปฏิบัติที่ดีที่สุด แต่ไม่สามารถใช้คู่มือดังกล่าวกับนักพัฒนาซอฟต์แวร์ในระหว่างการตรวจสอบโค้ด ในความเห็นส่วนตัวของฉันมาตรฐานการเข้ารหัสควรใกล้เคียงกับอัตโนมัติมากที่สุด มีเวลามากเสียในการวิจารณ์รหัสการโต้เถียงเรื่องการตั้งชื่อระยะห่างแท็บวงเล็บความคิดเห็น ฯลฯ ฯลฯ เมื่อทุกอย่างสามารถเป็นไปโดยอัตโนมัติ แม้แต่คำตอบเกี่ยวกับtablesและchairsสามารถเป็นไปโดยอัตโนมัติ LINT'ers อนุญาตให้ใช้พจนานุกรมการตรวจสอบตัวพิมพ์ใหญ่ต่อแนวคิด (ตัวแปร, ฟังก์ชั่น, วิธีการ, ชั้นเรียน ฯลฯ )

แม้แต่การตรวจสอบ JavaDoc ก็สามารถใช้งานได้โดย Robot LINT'er ก่อนที่จะยอมรับคำขอดึง โครงการโอเพนซอร์สจำนวนมากทำสิ่งที่แน่นอนนี้ คุณส่งคำขอดึงรหัสของคุณถูกสร้างขึ้นด้วยไฟล์ Travis-CI รวมถึงการวิเคราะห์แบบคงที่และต้องผ่านมาตรฐานการเข้ารหัสทั้งหมดซึ่งสามารถแสดงออกได้อย่างเป็นกลาง ไม่มีคนตีระฆังเกี่ยวกับการ 'ทำมันไม่ถูกต้อง' หรือไม่ 'ให้คุณค่า' กับความคิดเห็นหรือวิธีที่ผิดในการตั้งชื่อตัวแปรและอื่น ๆ การสนทนาเหล่านั้นไม่ได้ให้คุณค่าใด ๆ และเป็นสิ่งที่ดีที่สุดสำหรับหุ่นยนต์ของบุคคลที่สาม

ในการตอบคำถามจริงเราจะต้องกล่าวถึงวิธีการเขียนมาตรฐานซึ่งระบุวิธีตอบคำถามต่อไปนี้: ความคิดเห็นนี้มีคุณค่าหรือไม่? มาตรฐานการเข้ารหัสไม่สามารถกำหนด 'คุณค่า' ของความคิดเห็นได้ ดังนั้นมนุษย์จึงจำเป็นต้องผ่านรายการตรวจสอบนั้น เพียงการกล่าวถึงความคิดเห็นในมาตรฐานการเข้ารหัสจะสร้างรายการตรวจสอบที่ผู้โพสต์ดั้งเดิมต้องการหลีกเลี่ยง

นั่นเป็นเหตุผลที่คอมไพเลอร์มักไม่ประมวลผลความคิดเห็นและแยกออก ไม่สามารถระบุมูลค่าของพวกเขาได้ ความคิดเห็นในคำถามมีค่าหรือไม่ ใช่หรือไม่?. ตอบคำถามนี้คือ NP-hard มีเพียงมนุษย์เท่านั้นที่มีโอกาสตอบคำถามได้อย่างถูกต้องและถึงแม้จะสามารถตอบได้เมื่อผู้อ่านกำลังอ่าน ที่ค่าของความคิดเห็นนั้นได้รับผลกระทบจากสภาพอากาศชีวิตในบ้านของเขาหรือเธอการประชุมครั้งล่าสุดที่พวกเขาเพิ่งเข้าร่วมและไม่ได้จบลงอย่างดีเวลาของวันปริมาณกาแฟที่พวกเขามี ฉันเชื่อว่าภาพจะชัดเจนยิ่งขึ้น

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

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

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

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

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

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

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

เรามีความคิดเห็นสองประเภท:

ความเห็นที่เครื่องอ่านได้

สไตล์ความคิดเห็นเช่น Javadoc, JSDoc, Doxygen ฯลฯ เป็นวิธีการแสดงความคิดเห็นในส่วนต่อประสานสาธารณะที่มีชุดโค้ดให้ อินเทอร์เฟซนั้นสามารถใช้งานได้โดยผู้พัฒนารายอื่นเพียงคนเดียว (รหัสที่เป็นกรรมสิทธิ์สำหรับทีมสองคน) จำนวนนักพัฒนาที่ไม่รู้จัก (เช่น JMS) หรือสำหรับทั้งแผนก รหัสนี้สามารถอ่านได้โดยกระบวนการอัตโนมัติซึ่งจะสร้างวิธีการอ่านความคิดเห็นเหล่านั้น ala HTML, PDF และอื่น ๆ

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

ฉันกำลังทำสิ่งที่ดูบ้า แต่ก็ไม่จริง

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

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

ความคิดเห็นไม่สามารถเชื่อถือได้

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

นี่อาจฟังดูแปลก ๆ แต่ทนกับฉัน ข้อใดของสองบรรทัดนี้สำคัญ?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

ในตัวอย่างนี้สิ่งที่สำคัญคือเราไม่มีความคิดว่า 'n' คืออะไรไม่มีการตรวจสอบสำหรับ n เป็น 0 และแม้ว่าจะมีไม่มีอะไรหยุดนักพัฒนาจากการวางn = 0หลังจากการตรวจสอบสำหรับ 0 ดังนั้นความคิดเห็น ไม่มีประโยชน์และไม่มีอะไรอัตโนมัติสามารถจับสิ่งนี้ได้ ไม่มีมาตรฐานที่สามารถจับสิ่งนี้ได้ ความคิดเห็นในขณะที่สวย (บางคน) ไม่มีผลต่อผลลัพธ์ของผลิตภัณฑ์

ทดสอบการพัฒนาขับเคลื่อน

ผลิตภัณฑ์มีผลอะไรบ้าง? อุตสาหกรรมที่รหัสที่เขียนนั้นสามารถบันทึกหรือฆ่าใครบางคนได้อย่างจริงจัง สิ่งนี้ทำผ่านบทวิจารณ์โค้ด, บทวิจารณ์โค้ด, การทดสอบ, การทดสอบ, บทวิจารณ์โค้ด, การทดสอบหน่วย, การทดสอบแบบบูรณาการ, การทดสอบ, การทดสอบ, การทดสอบระยะเวลาหลายเดือน, บทวิจารณ์โค้ดและการทดลองเดี่ยว ๆ ไปสู่การผลิต ความคิดเห็นไม่มีส่วนเกี่ยวข้องกับสิ่งนี้

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

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

ข้อสรุป

หากคุณทำงานใน บริษัท ที่ต้องการทุกความคิดเห็นฉันรับประกันว่าอย่างน้อยสองวิศวกรซอฟต์แวร์ในโครงการได้เขียนโปรแกรมเอกสารอัตโนมัติใน Perl, Lisp หรือ Python ซึ่งกำหนดความคิดทั่วไปของสิ่งที่สายทำ จากนั้นเพิ่มความคิดเห็นด้านบนบรรทัดนั้น เนื่องจากเป็นไปได้ที่จะทำมันหมายความว่าความคิดเห็นที่ไร้ประโยชน์ ค้นหาวิศวกรที่เขียนสคริปต์เหล่านี้เพื่อจัดทำรหัสโดยอัตโนมัติและใช้เป็นหลักฐานว่าทำไม 'ความคิดเห็นในทุกบรรทัด' จึงเสียเวลาไม่มีค่าและอาจเป็นอันตรายได้

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

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

ความคิดเห็นไม่มีส่วนเกี่ยวข้องกับการช่วยชีวิต ความคิดเห็นมีไว้สำหรับมนุษย์มนุษย์ทำผิดพลาดแม้เมื่อเขียนความคิดเห็น อย่าไว้ใจมนุษย์ เออไม่เชื่อความคิดเห็น ความเห็นไม่ใช่ทางออกของคุณ

มีสองสิ่งที่แตกต่างที่คุณพูดถึงเมื่อคุณพูดถึงความคิดเห็น พวกเขาไม่เหมือนกันและความแตกต่างเป็นสิ่งสำคัญ

เอกสารประกอบจะบอกคุณเกี่ยวกับบิตนอกของรหัสชิ้นส่วน - ส่วนต่อประสาน

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

อินเทอร์เฟซทั้งหมดควรได้รับการบันทึกไว้ (เช่นแต่ละวิธียกเว้นวิธีส่วนตัว) และควรอธิบายถึงอินพุตเอาต์พุตและความคาดหวังข้อ จำกัด อื่น ๆ โดยเฉพาะอย่างยิ่งสิ่งที่ไม่สามารถแสดงออกผ่านข้อ จำกัด การทดสอบและอื่น ๆ ( รายละเอียดที่แน่นอนและตำแหน่งที่จะไปนั้นขึ้นอยู่กับโครงการ)

เอกสารที่ดีช่วยให้ผู้บริโภคที่มีศักยภาพตัดสินใจได้ว่าจะใช้รหัสเมื่อใดและอย่างไร

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

ความคิดเห็นจะอ่านอยู่เสมอในบรรดารหัสที่สำคัญ

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

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

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

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

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

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

โดยสรุปมาตรฐานการเข้ารหัสของคุณสามารถและควรต้องมีเอกสารประกอบ (การตรวจสอบอัตโนมัติช่วยตรวจสอบฟังก์ชัน / วิธีการที่ไม่มีเอกสาร แต่มนุษย์ยังต้องตรวจสอบว่าเอกสารนั้นดีหรือไม่) ความคิดเห็นเป็นการเรียกวิจารณญาณและคู่มือสไตล์ของคุณควรรับทราบนี้ ผู้ที่ไม่เคยแสดงความคิดเห็นและผู้ที่แสดงความคิดเห็นโดยไม่ต้องคิดควรคาดหวังว่าจะได้รับการท้าทาย

คุณไม่สามารถประมวลผลมาตรฐานการแสดงความคิดเห็นได้เนื่องจากคุณไม่สามารถรู้ได้ว่าอะไรคือความคิดเห็นที่สำคัญล่วงหน้า

แต่คุณยังต้องการตรวจสอบให้แน่ใจว่ามีการแสดงความคิดเห็นรหัสอย่างถูกต้องเนื่องจากนี่เป็นรหัสวิกฤติของชีวิต การแก้ปัญหาคือต้องมีมาตรฐานสำหรับการตรวจสอบโค้ด - กำหนดให้ต้องมีการตรวจสอบความคิดเห็นของโค้ดเกี่ยวกับความเข้าใจ

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

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

รหัสที่อ่านไม่ได้คือในระดับหนึ่งไม่สามารถหลีกเลี่ยงได้ เนื่องจากผู้เขียนจมอยู่ในบริบทและจะเห็นบางสิ่งบางอย่างที่ชัดเจนเมื่อเห็นได้ชัดก็ต่อเมื่อคุณรู้จัก x, y หรือ z

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

แสดงความคิดเห็นทุกบรรทัดของรหัส? ไม่

วัตถุประสงค์ของกฎอื่น ๆ ที่คุณพูดถึงคือหลีกเลี่ยงสิ่งนั้นอย่างแม่นยำ

ความคิดเห็นต่อรหัสที่อ่านได้นั้นมีความซ้ำซ้อนที่สุดและที่แย่ที่สุดจะทำให้ผู้อ่านมองหาจุดประสงค์ที่ไม่มีอยู่จริงของความคิดเห็น

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

ฉันจะบอกว่าอย่างดีที่สุดรหัสไม่ควรต้องการความคิดเห็นใด ๆ นอกเหนือจากเอกสาร

มีสไตล์ที่ไปตรงกันข้ามทั้งหมดถ้าคุณมีข้อสงสัยเกี่ยวกับเส้นมันทั้ง:

1. รหัสมีความซับซ้อนเกินไปและควรได้รับการปรับเปลี่ยนใหม่ในฟังก์ชั่นที่มีชื่อที่มีความหมายความหมายสำหรับส่วนของรหัส ไม่ว่าจะเป็นความซับซ้อนifหรือบางส่วนของอัลกอริทึม (หรือ LINQ หนึ่งซับที่ฉลาด)

2. ถ้ามันไม่สามารถทำให้เป็นเรื่องง่ายได้คุณก็ไม่รู้ภาษาที่เพียงพอ

(โดยส่วนตัวแล้วฉันไม่ใช่คนที่คลั่งไคล้ในกฎการไม่แสดงความคิดเห็นที่เข้มงวด แต่ฉันคิดว่ามันเป็นความคิดเริ่มต้นที่ดีที่จะต้องดำเนินการ)

ให้ทั้งหมดนี้เป็นไปได้ที่จะเขียนมาตรฐานการเข้ารหัสที่ดีที่จับความคิดนี้

สำหรับกระบวนการ มาตรฐานของเราให้เครดิตแก่ผู้ตรวจสอบค่อนข้างมาก สมมติว่าพวกเขาไม่เป็นอันตรายนี่ใช้งานได้ดี

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

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

ยังไม่มีตายตัว แม้ว่าเราจะเป็นกลุ่มเล็ก ๆ มันง่ายที่จะหาฉันทามติในกลุ่ม 5

คำถาม:

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

ความคิดเห็นไม่ควรพยายามให้ความรู้แก่ผู้อ่านเกี่ยวกับภาษา ผู้อ่านควรสันนิษฐานว่ารู้ภาษาดีกว่าผู้เขียน แต่มีบริบทน้อยกว่านักเขียน

ผู้อ่านของรหัสนี้จากตัวอย่างของคุณควรรู้ว่าexit()จะออกจากแอปพลิเคชัน - จึงทำให้ความคิดเห็นซ้ำซ้อน:

/* Exit the application */
exit();

ความคิดเห็นที่ซ้ำซ้อนเป็นการละเมิด DRY และการเปลี่ยนแปลงโค้ดไม่จำเป็นต้องเผยแพร่ไปยังความคิดเห็นทิ้งความคิดเห็นที่ไม่สะท้อนสิ่งที่รหัสกำลังทำอยู่

อย่างไรก็ตามความคิดเห็นที่อธิบายว่าทำไมคุณถึงทำอะไรบางอย่างอาจมีค่าโดยเฉพาะอย่างยิ่งถ้าคุณไม่สามารถสื่อสารความหมายในโค้ดได้อย่างง่ายดาย

Python PEP 8 (คู่มือสไตล์สำหรับ Python ในไลบรารีมาตรฐาน CPython) ให้แนวทางต่อไปนี้สำหรับความคิดเห็นแบบอินไลน์:

ใช้ความคิดเห็นแบบอินไลน์เท่าที่จำเป็น

ความคิดเห็นแบบอินไลน์คือความคิดเห็นในบรรทัดเดียวกันกับคำสั่ง ความคิดเห็นแบบอินไลน์ควรคั่นด้วยช่องว่างอย่างน้อยสองช่องจากคำสั่ง พวกเขาควรเริ่มต้นด้วย # และช่องว่างเดียว

ความคิดเห็นแบบอินไลน์นั้นไม่จำเป็นและในความเป็นจริงแล้วเสียสมาธิหากสิ่งเหล่านั้นแสดงให้เห็นชัดเจน อย่าทำสิ่งนี้:

x = x + 1                 # Increment x

แต่บางครั้งสิ่งนี้มีประโยชน์:

x = x + 1                 # Compensate for border

จากตัวอย่างดังกล่าวส่วนตัวแล้วผมชอบที่จะก้าวไปอีกขั้นหนึ่งและพยายามที่จะกำจัดความคิดเห็นนี้เช่นกัน ตัวอย่างเช่นฉันอาจมาถึงที่:

border_compensation = 1
compensated_x = x + border_compensation

ทำให้รหัสของคุณตนเอง documenting ไม่เป็นความคิดใหม่

กลับไปที่คำถามจริง:

ให้ทั้งหมดนี้เป็นไปได้ที่จะเขียนมาตรฐานการเข้ารหัสที่ดีที่จับความคิดนี้

ฉันเชื่อว่าแนวทางและตัวอย่างของ PEP 8 แสดงให้เห็นถึงมาตรฐานการเข้ารหัสที่ดีซึ่งรวบรวมความคิดนี้ ใช่ฉันเชื่อว่าเป็นไปได้

ฉันคิดว่าเมื่อคุณเห็นการแสดงความคิดเห็นแบบนี้และฉันเขียนด้วยตัวเองในบางครั้งมันเป็นเพราะผู้เขียนกำลังเขียนสเป็คในความคิดเห็นจากนั้นจะผ่านและดำเนินการแต่ละความคิดเห็น

หากเราถูกท้าทายให้เขียนมาตรฐานการเข้ารหัสซึ่งสร้างรหัสซึ่งสามารถเข้าใจได้ในแง่ของฟังก์ชั่นที่ต้องการมากกว่าการใช้งานจริง (เพื่อให้สามารถระบุข้อผิดพลาดได้) จากนั้นเราจะพูดถึงการกำหนดคุณสมบัติเอกสารและเชื่อมโยงกับ ผลิตภัณฑ์สุดท้าย?

แก้ไข ----

เพียงชี้แจง ฉันไม่ได้รับความเห็นเกี่ยวกับการทดสอบ vs tdd กับหน่วยที่ดีที่สุด หรือการแนะนำความคิดเห็นต่อบรรทัดนั้นดี / ไม่ดี

ฉันแค่เสนอเหตุผลที่คุณอาจเห็นรูปแบบของการแสดงความคิดเห็นที่พูดคุยในตัวอย่าง

และจากการตั้งคำถามว่ามาตรฐานการเข้ารหัสเกี่ยวกับการแสดงความคิดเห็นจะเป็นจริงได้ดีกว่าเขียนเป็นข้อกำหนดเอกสารข้อกำหนดบางชนิด

ความคิดเห็นเช่นสำหรับการอธิบายวัตถุประสงค์ของรหัสซึ่งก็คือสเป็คคืออะไร

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

สิ่งนี้เห็นได้ชัดว่าเหนือกว่าเอกสารอื่น ๆ - นี่เป็นวิธีการที่โครงสร้างมีการเลือกอัลกอริธึมและอื่น ๆ ซึ่งอาจสัมผัสกับการวิเคราะห์และออกแบบข้อกำหนด

กฎ # 1 ของฉันคือ "ไม่ต้องจัดทำเอกสารที่ชัดเจน" กฎ # 2 คือ "เขียนรหัสที่ชัดเจน"

สำหรับรหัสความปลอดภัยที่สำคัญ (ซึ่งฉันไม่เคยทำงานขอบคุณพระเจ้า) นี่เป็นสิ่งที่จำเป็น แต่ไม่มีที่ไหนเลยใกล้ขั้นตอนแรกที่เพียงพอ มันอาจจะต้องลงมาเพื่อกำหนดคุณสมบัติของภาษาที่ต้องหลีกเลี่ยง (ฉันเคยเห็นมากกว่าหนึ่งคำสั่งมาตรฐาน "คุณจะไม่ใช้scanf( "%s", input ); ด้วยเหตุผลใดก็ตาม ")

แนวปฏิบัติที่ดีที่สุดของการจัดทำเอกสารด้วยตนเองไม่ใช่ข้อตกลงหลัก แต่เป็นที่ยอมรับกันอย่างกว้างขวางว่ารหัสที่เข้าใจง่ายดีกว่ารหัสที่มีความลับไม่ใช่ทุกคนเห็นด้วยว่ารหัสที่ซับซ้อนจะต้องได้รับการปรับสภาพใหม่หรือไม่ มัน.

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

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

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

ปัญหานี้เป็นปัญหาเพราะเมื่อความคิดเห็นส่วนใหญ่ที่คุณอ่านซ้ำซ้อนคุณหยุดให้ความสนใจกับพวกเขา (เพราะคุณรู้ว่าพวกเขาจะเป็นขยะซ้ำซ้อน) จากนั้นคุณจะพลาดความคิดเห็นที่สำคัญ ดังนั้นฉันพูด - เขียนเฉพาะความคิดเห็นที่สำคัญดังนั้นเมื่อมีคนเห็นความคิดเห็นในรหัสพวกเขาจะรู้ว่ามันคุ้มค่าที่จะอ่านเพื่อทำความเข้าใจโค้ด

IMHO มันควรทำทั้งสองอย่าง การแสดงความคิดเห็นทุกบรรทัดเป็นเรื่องโง่เพราะคุณท้ายเรื่องชอบ

  i++;    /* Increment i */

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

OTOH ถ้าคุณเขียนบล็อกความคิดเห็นที่ดีที่ส่วนหัวของฟังก์ชั่น (หรือการจัดกลุ่มใดก็ตามที่มีเหตุผล) อธิบายทั้งสิ่งที่ต้องทำให้สำเร็จและวิธีการถ้ามันน้อยกว่าที่เห็นได้ชัดคุณมีบางสิ่งที่มีประโยชน์ หากคุณเป็นฉันคุณอาจรวมรหัส LaTeX สำหรับสมการที่เกี่ยวข้องหรือการอ้างอิงไปยังเอกสารเช่น "นี่เป็นการดำเนินการตามแผน WENO สำหรับการแก้สมการแฮมิลตัน - จาโคบีดังที่กล่าวไว้ใน ... "

ได้เวลานำแผนภูมิการไหลกลับมาแล้ว! (ไม่จริงๆ แต่แขวนในนาที)

วันก่อนฉันพบแม่แบบแผนภูมิลำดับงานเก่าของฉัน ฉันใช้เพื่อทำการบ้านและเรื่องตลกเท่านั้น (คุณต้องชอบผังงานที่โง่ ๆ ) แต่ถึงตอนนี้โปรแกรมเมอร์เชิงพาณิชย์ส่วนใหญ่ที่ยังคงใช้โฟลว์ชาร์ตก็ยังสร้างมันขึ้นมาโดยอัตโนมัติจากโค้ด (ซึ่งทำลายวัตถุประสงค์เดิมของผังงานทั้งหมดซึ่งจะช่วยในการเขียนโค้ดที่ดีขึ้นและค่อนข้างมีประโยชน์ในรหัสเครื่อง อย่างไรก็ตามด้วยภาษาระดับสูงกว่าแผนผังลำดับงานเปลี่ยนจากการเป็นไม้ยันรักแร้เป็น hoble ทำไมนามธรรมของผังงานเป็นเช่นเดียวกับรหัสความคิดเห็นที่แสดงเป็น hobble ในระดับเดียวกันกับการเป็นนามธรรม ความคิดเห็นที่ดีอยู่ในระดับที่แตกต่างจากสิ่งที่เป็นนามธรรมรหัสวิธีที่ง่ายที่สุดในการทำเช่นนี้คือการใช้ความเห็นว่าทำไมในขณะที่รหัสจัดการสิ่งที่

ฉันจะตอบคำถามตามที่ระบุไว้:

ให้ทั้งหมดนี้เป็นไปได้ที่จะเขียนมาตรฐานการเข้ารหัสที่ดีที่จับความคิดนี้

ใช่. WYSIWYG มาตรฐานการเข้ารหัสที่ดีคือตัวอักษร " ชัดเจนต่อผู้อ่านว่าโค้ดต่อไปนี้ทำอะไรและทำไม "

ในคำอื่น ๆ รหัสของฉันตรวจสอบความคิดเห็นเกี่ยวกับการอ่านรหัสแท้จริง 1-1 เกิดขึ้นจากสภาพจิตใจของฉัน

ฉันในฐานะผู้อ่าน (ที่ดีกว่ายังเป็นมาตรฐานขั้นต่ำเป็นแบบจำลองทางจิตของผู้อ่านที่มีประสบการณ์น้อย แต่มีเหตุผล) จะไม่เข้าใจวัตถุประสงค์ของรหัสต่อไปนี้หรือวิธีการทำงาน

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

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

มาตรฐานที่สองที่ต้องระบุอย่างชัดเจนคือ "การทดสอบฉุกเฉิน 2am"

การสำรองข้อมูลของคุณซึ่งไม่ได้รับประสบการณ์เกี่ยวกับรหัสนี้สามารถระบุได้ว่าปัญหานี้เกิดขึ้นกับรหัสใดเมื่อทำการดีบั๊กในระหว่างการเรียกสะพานฉุกเฉินในกรณีผลิต 2am เมื่อคุณไปเที่ยวพักผ่อนในแถบเทือกเขาแอนดีสของชิลี

สิ่งนี้อาจฟังดูเป็นเรื่องส่วนตัว แต่จริง ๆ แล้วง่ายต่อการวัดจริง: โทรหาสมาชิกทีมจูเนียร์สุ่มที่คาดว่าจะเป็นคนดีบั๊กตอนกลางคืนในกรณีฉุกเฉินในการผลิต ที่นั่น

คำตอบนี้ครอบคลุมถึงปัญหาส่วนใหญ่อย่างไรก็ตามมีสิ่งหนึ่งที่สำคัญ

ฉันต้องการรวบรวมแนวคิดตามบรรทัดของ: พิจารณาความคิดเห็นสำหรับทุกบรรทัดลำดับคำสั่งส่วนโครงสร้างโครงสร้างฟังก์ชั่นวิธีการเรียนแพคเกจส่วนประกอบส่วนประกอบ ... ของรหัส

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

คำตอบที่มีอยู่จำนวนมากมีรายละเอียดดี แต่ฉันรู้สึกว่าสำคัญที่จะต้องตอบ:

... [ความคิดเห็น] ที่จะมีความเกี่ยวข้องในการตรวจสอบแบบเพื่อน แต่จะไม่เปลี่ยนเป็นรายการตรวจสอบที่ไม่สนใจ ...

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

ที่ถูกกล่าวว่านี้เป็นอัตนัยสิ่งที่เครื่องมือที่ใช้โดยนักพัฒนาและไม่ได้ความคิดเห็นทั้งหมดที่ใช้โดยซอฟต์แวร์ดังกล่าวจะเป็นประโยชน์ที่แต่ละอื่น ๆ