วิธีการอ้างถึงพื้นที่เฉพาะของรหัสในเอกสารประกอบ?

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

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

ฉันได้พิจารณาทิ้งรหัสด้วยความคิดเห็นที่ชอบ:

/* linetag 38FECD4F */

โดยที่ "38FECD4F" เป็นแท็กที่ไม่ซ้ำกันสำหรับบรรทัดนั้น จากนั้นฉันสามารถใส่เอกสาร "ในบรรทัดที่ติดแท็ก '38FECD4F' โปรดสังเกตว่าเกิดขึ้นเช่นนั้น"

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

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

ฉันมักจะไม่เจอสถานการณ์เช่นนี้ที่ฉันต้องอ้างถึงบรรทัด exect # ในความคิดเห็นบางส่วนที่เขียนที่อื่น - รหัสโดยทั่วไปจะมีเอกสารที่ถูกเขียน

ฉันไม่รู้วิธีมาตรฐานในการทำเช่นนี้ - แต่อยู่ด้านบนของหัวของฉัน ...

คุณสามารถอ้างถึงส่วนของรหัสผ่านบริบทของมัน - คือสิ่งที่ล้อมรอบพวกเขา

สังเกตเห็นความหมายเหนือคำนิยามของ func1 () ที่เกิดขึ้นเช่นนั้น

โปรดทราบว่าหลังจาก for for loop ที่วนซ้ำ recordXYZItr เราก็เรียกเมธอด gc ()

ข้อควรระวัง: ในเมธอด yahoo () หลังจากการประกาศตัวแปร PQ เรายังทำการสลับค่าใน A และ B ดังนั้นวัตถุ mapABC ก็จำเป็นต้องคัดลอก

อีกวิธีหนึ่งคือการเพิ่มแท็กอธิบาย แทนที่จะพูดอะไรทำนอง38FECD4Fนั้นคุณสามารถพูดSome XYZ implementationหรือBUGFIX 1474อ้างถึงสิ่งนั้นได้

มันขึ้นอยู่กับวิธีการเขียนโค้ดและฉันเข้าใจว่ามันอาจทำให้เกิดการรีแฟคเตอร์จำนวนมากที่คุณไม่ได้อยู่ที่นี่

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

ฉันขอแนะนำให้คุณใช้วิธีอื่นนอกเหนือจากการเชื่อมโยงจากเอกสารภายนอกรหัสไปยังรหัส:

1. เพิ่มความคิดเห็นในรหัสของคุณโดยใช้เครื่องมือเช่นDoxygen

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

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