การบำรุงรักษารหัส: ในการเพิ่มความคิดเห็นในรหัสหรือเพียงแค่ปล่อยไว้ในการควบคุมเวอร์ชัน?

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

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

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

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

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

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

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

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

ดังนั้นแทนที่จะ

// fixed bug XXXXX on 10/9/2012

คุณอาจมีความคิดเห็นที่ระบุว่า

// doing X, because otherwise Y will break.

หรือ

// doing X, because doing Y is 10 times slower.

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

ความสามารถในการอ่านของซอร์สโค้ดเป็นสิ่งสำคัญยิ่ง codebase ที่เต็มไปด้วยความคิดเห็นที่ให้ประวัติเต็มของ bug ทุกตัวและ CR ที่ทำนั้นจะไม่สามารถอ่านได้เลย

แต่อย่าข้ามความคิดเห็นอย่างสมบูรณ์: ความคิดเห็นที่ดี (ไม่ใช่การบันทึกเอกสารทุกครั้งที่เริ่ม / หยุด / คำอธิบาย / วิธีแก้ปัญหาของทุก bugfix และ CR) เพิ่มความสามารถในการอ่านรหัส ตัวอย่างเช่นสำหรับบิตของรหัสที่ยุ่งยากหรือไม่ชัดเจนที่คุณเพิ่มเพื่อแก้ไขข้อบกพร่องความคิดเห็นของแบบฟอร์ม// fix ISSUE#413บอกผู้คนว่าจะหาข้อมูลเพิ่มเติมในตัวติดตามปัญหาของคุณได้ที่ไหนเป็นแนวคิดที่ยอดเยี่ยม

ความคิดเห็นในรหัสที่มีเกี่ยวกับสิ่งที่รหัสคือในขณะนั้น การถ่ายภาพในเวลาใดก็ตามไม่ควรอ้างถึงรหัสรุ่นเก่า (หรือแย่กว่านั้นในอนาคต)

ความคิดเห็นใน VCS เกี่ยวกับการเปลี่ยนแปลงของรหัส พวกเขาควรอ่านเป็นเรื่องราวเกี่ยวกับการพัฒนา

ตอนนี้การเปลี่ยนแปลงทุกอย่างควรมีความคิดเห็นหรือไม่ ในกรณีส่วนใหญ่ใช่ ข้อยกเว้นเดียวที่ฉันจินตนาการคือเมื่อพฤติกรรมที่คาดหวังได้รับการบันทึกไว้แล้ว แต่ไม่ใช่สิ่งที่คุณได้รับเนื่องจากข้อผิดพลาด การแก้ไขมันทำให้ความคิดเห็นที่มีอยู่แม่นยำยิ่งขึ้นดังนั้นจึงไม่จำเป็นต้องเปลี่ยนแปลง ข้อผิดพลาดของตัวเองควรได้รับการบันทึกไว้ในประวัติตั๋วและคอมมิชชันคอมเม้นท์ แต่ในรหัสเท่านั้นหากรหัสดูแปลก ในกรณีนั้น a // make sure <bad thing> doesn't happenควรเพียงพอ

ความคิดเห็นประเภทหนึ่งที่ฉันซาบซึ้งคือ:

// สิ่งนี้นำมาใช้สำหรับกฎธุรกิจ 5 ของข้อเสนอ 2

หรืออะไรก็ตามที่คุณใช้เพื่อรวบรวมความต้องการของคุณ

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

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

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

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

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

มีข้อยกเว้นน้อยมากการติดตามการเปลี่ยนแปลงและการอ้างอิงปัญหาคืองานของ VCS, IMNSHO

ฉันมักจะปฏิบัติตามกฎนี้: หากการเปลี่ยนแปลงมีความชัดเจนและรหัสผลลัพธ์ไม่ได้ตั้งคำถามไม่เปลี่ยนกลับหรือเปลี่ยนแปลงพฤติกรรมก่อนหน้านี้อย่างมีนัยสำคัญในลักษณะที่เป็นรูปธรรม - จากนั้นทิ้งไว้ใน VCS เพื่อติดตามหมายเลขข้อผิดพลาดและข้อมูลการเปลี่ยนแปลงอื่น ๆ

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

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

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

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

ไฟล์เก่าบางไฟล์ในเคอร์เนล Linux มีบล็อกความคิดเห็นประวัติขนาดใหญ่ วันที่เหล่านั้นย้อนกลับไปเมื่อไม่มีระบบควบคุมเวอร์ชันเพียง tarballs และแพตช์

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

ความคิดเห็นโดยละเอียดเป็นที่ต้องการในความคิดเห็นในการเช็คอิน

ฉันต้องการรวมรายละเอียดเกี่ยวกับข้อมูลแบ็คกราวด์รายละเอียดของโซลูชันที่ไม่ได้ใช้งานเนื่องจากผลข้างเคียงบางอย่าง

Pramagic โปรแกรมเมอร์และ CleanCode นำไปสู่แนวทางดังต่อไปนี้

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