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

มันเป็นการดีหรือไม่ที่จะใส่หมายเลขบั๊กในไฟล์ลงในความคิดเห็นส่วนหัว?

ความคิดเห็นจะมีลักษณะเช่นนี้:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

ดูเหมือนว่ามีประโยชน์ แต่ก็ถือว่าเป็นการปฏิบัติที่ไม่ดี?

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

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

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

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

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

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

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

เลขที่

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

มันเป็นความคิดที่แย่มาก IMHO หลังจากแก้ไขจำนวน 100 คุณจะมีความคิดเห็น 90% และรหัส 10% ฉันจะไม่พิจารณาว่าสะอาดและอ่านได้

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

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

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

ใช่มันแยกรหัส แต่ช่วยในการค้นหาสาเหตุที่ทำให้รหัสนั้นมี

หนึ่งในคะแนนในการทดสอบ Joelคือ

คุณมีฐานข้อมูลบั๊กหรือไม่

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

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

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

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

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

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

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

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

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

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

ฉันรู้ว่าGitไม่ได้ทำสิ่งนี้และคำตอบง่ายๆคือ "ทำไมบนโลกนี้ถึงไปที่นั่น"

มันเป็นการออกแบบแบบแยกส่วนที่น้อยกว่าโดยทั่วไป ภายใต้โซลูชันนี้ตอนนี้ไฟล์ต่างกันระหว่างเนื้อหาและเมตาดาต้า Amazon S3เป็นอีกตัวอย่างหนึ่งของบริการสำหรับการจัดเก็บไฟล์ที่ไม่ได้เพิ่มYAML front- storyหรือไฟล์ที่ชอบ

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

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

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

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

หากคุณกำลังมองหาที่ดีอ่านในเรื่องนี้ผมขอแนะนำให้บทที่สี่ของรหัสที่สะอาด

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

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

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

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

ข้อมูลข้อผิดพลาดใด ๆ ที่เกี่ยวข้องโดยตรงกับชิ้นส่วนของรหัสไม่เกี่ยวข้องเมื่อความสมบูรณ์ของการเปลี่ยนแปลงทั้งหมดได้รับการแก้ไขโดยการแก้ไขต่อเนื่อง

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

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

ฉันจะไม่ใส่ข้อมูลดังกล่าวในตอนเริ่มต้นของไฟล์ - โดยปกติสิ่งนั้นจะเป็นของระบบตั๋ว

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

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

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

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