มันเป็นการดีที่จะแสดงความคิดเห็นด้วยหมายเลขปัญหา?

ผมเห็นตัวเลขปัญหามากมายจากความคิดเห็นของรหัส jQuery (ที่จริงแล้วมีปัญหา 69 รายการในรหัส jQuery) ฉันคิดว่ามันจะเป็นแนวปฏิบัติที่ดี แต่ฉันไม่เคยเห็นแนวทางใด ๆ

หากเป็นการปฏิบัติที่ดีแนวทางในการฝึกนี้คืออะไร?

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

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

ตัวอย่างเช่น:

Bug # 203: การเชื่อมต่อฐานข้อมูลไม่หมดเวลาหลังจาก 30 วินาที

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

ฉันไม่เห็นด้วยกับโปสเตอร์อื่น ๆ ที่นี่!

ความคิดเห็นเกี่ยวกับโค้ดที่มีการอ้างอิงการติดตามอาจเป็นประโยชน์อย่างมากสำหรับการเขียนโปรแกรมบำรุงรักษา

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

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

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

ฉันคิดว่าการอ้างอิงเล็ก ๆ น้อย ๆ เหล่านี้กับระบบติดตามบั๊กของคุณนั้นดีกว่าที่จะแสดงความคิดเห็นโดยละเอียดในโค้ด

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

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

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

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

ฉันคิดว่ามันเป็นแนวปฏิบัติที่ดีในการอ้างถึงปัญหาสำหรับการอ่านเพิ่มเติมในขณะที่ให้คำอธิบายสั้น ๆ ในความคิดเห็นของตัวเอง

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

ตัวอย่างเช่น:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

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

หรือ:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

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

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

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

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