ผู้พัฒนาระดับสูงในร้านของเรายืนยันว่าเมื่อใดก็ตามที่มีการแก้ไขโค้ดโปรแกรมเมอร์ที่รับผิดชอบควรเพิ่มความคิดเห็นแบบอินไลน์ที่ระบุสิ่งที่เขาทำ ความคิดเห็นเหล่านี้มักจะดูเหมือน// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

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

นี่เป็นวิธีปฏิบัติที่เป็นมาตรฐาน (หรืออย่างน้อยสามัญ) ในร้านค้าอื่นหรือไม่?

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

อย่างไรก็ตามฉันยังคงทำอะไรแบบนี้กับการแก้ไขเฉพาะบางประเภท

กรณีที่ 1 - ภารกิจ

หากคุณใช้ IDE เช่น Eclipse, Netbeans, Visual Studio (หรือมีวิธีการค้นหาข้อความบนโค้ดเบสของคุณด้วยสิ่งอื่น) บางทีทีมของคุณอาจใช้ "แท็กความคิดเห็น" หรือ "แท็กงาน" ในกรณีนี้จะมีประโยชน์

ฉันต้องการตรวจสอบรหัสเป็นครั้งคราวเพิ่มสิ่งต่อไปนี้:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

หรือ:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

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

กรณีที่ 2 - แพทช์ Libs ของบุคคลที่สาม

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

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

กรณีที่ 3 - การแก้ไขที่ไม่ชัดเจน

อันนี้ค่อนข้างขัดแย้งและใกล้ชิดกับสิ่งที่นักพัฒนาอาวุโสของคุณขอ

ในผลิตภัณฑ์ที่ฉันทำงานในขณะนี้บางครั้งเรา(ไม่แน่นอนสิ่งทั่วไป) มีความคิดเห็นเช่น:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

เราจะทำเช่นนี้หากแก้ไขข้อบกพร่องไม่ชัดเจนและรหัสอ่านผิดปกติ กรณีนี้อาจเป็นปัญหาสำหรับเบราว์เซอร์ที่แปลกประหลาดหรือแก้ไข CSS ที่คลุมเครือที่คุณจำเป็นต้องใช้เนื่องจากมีข้อบกพร่องของเอกสารในผลิตภัณฑ์ ดังนั้นโดยทั่วไปเราจะเชื่อมโยงไปยังแหล่งเก็บข้อมูลปัญหาภายในของเราซึ่งจะมีการให้เหตุผลโดยละเอียดเกี่ยวกับตัวแก้ไขบั๊กและพอยน์เตอร์กับเอกสารของข้อผิดพลาดของผลิตภัณฑ์ภายนอก (เช่นคำแนะนำด้านความปลอดภัยสำหรับข้อบกพร่องของ Internet Explorer 6 หรือ อะไรแบบนั้น).

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

นี่เป็นเพียงตัวอย่างในชีวิตจริง

ในบางกรณีมันดีกว่าไม่มีอะไร :)

ฉันเพิ่งเจอคลาสการคำนวณทางสถิติขนาดใหญ่ใน codebase ของฉันซึ่งความคิดเห็นส่วนหัวอยู่ในรูปแบบของการเปลี่ยนแปลงที่มี yadda yadda ปกติ: ผู้ตรวจทานวันที่บั๊ก ID

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

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

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

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

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

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

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

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

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

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

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

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

หากไม่เข้าใจเหตุผลของเขาในเรื่องความต้องการคุณจะไม่สามารถโน้มน้าวเขาได้

ฉันทำงานกับผลิตภัณฑ์ Windows ที่มีอายุ 20 ปีขึ้นไป เรามีแนวทางปฏิบัติที่คล้ายคลึงกันซึ่งจัดมาเป็นเวลานาน ฉันไม่สามารถนับจำนวนครั้งที่การปฏิบัตินี้ช่วยเบคอนของฉันได้

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

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

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

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

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

ไม่อย่างนั้นฉันก็บอกได้

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