การเชื่อมโยงหลายมิติเอกสารรหัสที่มาภายนอก [ปิด]

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

เมื่อพิจารณาถึงอสังหาริมทรัพย์ที่กว้างขวางในสภาพแวดล้อมการพัฒนาที่ทันสมัย ​​(จอภาพความละเอียดสูง, จอภาพสองจอ ฯลฯ ) IDE สามารถจัดทำพาเนลกึ่งล็อคขั้นตอนที่ซอร์สโค้ดแยกออกจากสายตา - แต่เชื่อมโยงกับ - ความคิดเห็นที่เกี่ยวข้อง ตัวอย่างเช่นนักพัฒนาสามารถเขียนความคิดเห็นซอร์สโค้ดในภาษามาร์กอัปที่เชื่อมโยงหลายมิติ (เชื่อมโยงกับข้อกำหนดของซอฟต์แวร์เพิ่มเติม) ซึ่งจะช่วยป้องกันเอกสารจากการทำให้ยุ่งเหยิงซอร์สโค้ด

ข้อบกพร่องอะไรที่จะยับยั้งกลไกการพัฒนาซอฟต์แวร์เช่นนี้?

การจำลองเพื่อช่วยชี้แจงคำถาม:

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

ข้อดีที่เป็นไปได้ ได้แก่ :

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

บันทึก:

• หน้าต่างเอกสารสามารถยุบได้
• เวิร์กโฟลว์สำหรับการดูหรือเปรียบเทียบไฟล์ต้นฉบับจะไม่ได้รับผลกระทบ
• วิธีการใช้งานเกิดขึ้นเป็นรายละเอียด; เอกสารอาจเป็น:
  • เก็บไว้ที่ส่วนท้ายของไฟล์ต้นฉบับ;
  • แบ่งออกเป็นสองไฟล์โดยการประชุม ( filename.c, filename.c.doc); หรือ
  • ขับเคลื่อนด้วยฐานข้อมูลอย่างสมบูรณ์
• โดยเอกสารเชื่อมโยงหลายมิติฉันหมายถึงการเชื่อมโยงไปยังแหล่งข้อมูลภายนอก (เช่น StackOverflow หรือ Wikipedia) และเอกสารภายใน (เช่นวิกิบนโดเมนย่อยที่สามารถอ้างอิงเอกสารข้อกำหนดทางธุรกิจข้าม) และไฟล์ต้นฉบับอื่น ๆ (คล้ายกับ JavaDocs)

หัวข้อที่เกี่ยวข้อง: ความเกลียดชังกับเอกสารในอุตสาหกรรมคืออะไร?

ปัญหานี้รบกวนจิตใจฉันตลอดเวลาและฉันเพิ่งได้รับแนวคิดเกี่ยวกับทิศทางที่เราควรจะพยายามแก้ไข (นั่นคือวิธีที่ฉันพบคำถามนี้)

ฉันคิดว่าปัญหาเกี่ยวกับเอกสารที่เชื่อมโยงนั้นคิดผิดเมื่อเราตัดสินใจที่จะรวมเอกสารผู้ใช้ในซอร์สโค้ด เช่นเดียวกับ docco

ก่อนอื่นให้แยกความคิดเห็นรหัสจากเอกสารผู้ใช้

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

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

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

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

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

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

เกิดอะไรขึ้นถ้าแทนที่จะมีผลผูกพัน 2 ทางเรามีวิธีเดียว? เอกสารชี้ไปที่รหัส เราสามารถมีรหัส markdown ด้วยคำสั่งพิเศษเช่น:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

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

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

404 - ไม่พบหน้า

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

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

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

ข้อเสียที่เป็นไปได้ที่ฉันเห็น:

• คุณต้องมีโปรแกรมแก้ไขพิเศษที่ใช้คุณสมบัตินี้

• รหัสไม่ใช่แค่ข้อความธรรมดาอีกต่อไปง่ายต่อการจัดการและส่งมอบให้กับ VCS-es

• คุณต้องมีความกว้างของหน้าจอเพิ่มขึ้นอีกสองเท่าเพื่อให้ทำงานกับโค้ดได้

สำหรับข้อโต้แย้งของคุณ:

รหัสต้นฉบับเพิ่มเติมและเอกสารเพิ่มเติมบนหน้าจอพร้อมกัน

แต่อาจไม่สะดวกถ้าคุณต้องการดูไฟล์สองไฟล์เคียงข้างกัน

ความสามารถในการแก้ไขเอกสารเป็นอิสระจากซอร์สโค้ด (โดยไม่คำนึงถึงภาษา?)

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

เขียนเอกสารและซอร์สโค้ดขนานโดยไม่มีข้อขัดแย้งผสาน

อาจเป็นข้อเสียอีกครั้ง หากเอกสารของคุณสอดแทรกรหัสอย่างลึกซึ้งคุณจะแก้ไขได้อย่างไร

เอกสารไฮเปอร์ลิงก์แบบเรียลไทม์พร้อมการจัดรูปแบบข้อความที่เหนือกว่า

ถ้ามันอยู่ในรหัสมันเป็นแบบเรียลไทม์;) สำหรับไฮเปอร์ลิงก์การกระโดดไปที่นิยามนั้นถูกนำไปใช้ใน IDEs ส่วนใหญ่แล้ว

การแปลด้วยเครื่องเสมือนจริงแบบเรียลไทม์เป็นภาษาธรรมชาติที่แตกต่างกัน

ฉันไม่เห็นสาเหตุที่คุณไม่สามารถทำได้ด้วยความคิดเห็น / เอกสารปกติ

รหัสทุกบรรทัดสามารถเชื่อมโยงอย่างชัดเจนกับงานความต้องการทางธุรกิจและอื่น ๆ

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

เอกสารสามารถประทับเวลาโดยอัตโนมัติเมื่อเขียนโค้ดแต่ละบรรทัด (ตัวชี้วัด)

VCS-es ไม่ได้ให้ข้อมูลประเภทนี้หรือไม่

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

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

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

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

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

นอกจากสิ่งที่ @Bogdan แจ้งไปแล้วฉันจะเพิ่มอีกสองสามรายการ:

• ฉันกำหนดค่า IDE ของฉันให้มี 2 ไฟล์พร้อมกันเสมอ ด้วยคุณสมบัติที่คุณแนะนำฉันจะต้องใช้ 2 จอภาพเพื่อดูข้อมูลในจำนวนเดียวกันและ 3 เพื่อทำสิ่งที่ฉันทำตอนนี้ด้วย 2
• ในขณะที่เรียกดูไฟล์คุณจะไม่เห็นความคิดเห็นทันทีและหากคุณไม่ทราบว่าสิ่งที่คุณกำลังมองหามันเป็นเรื่องยากมากที่จะหามัน
• ขณะค้นหาไฟล์ฉันไม่สามารถค้นหาความคิดเห็นโดยตรง (หรือง่าย)
• บางครั้งฉันต้องทำแบบทดสอบต่างๆ / เขียนชิ้นสั้น ๆ ของรหัสบนเซิร์ฟเวอร์สดผ่านSSH แม้ว่าฟังก์ชั่นที่คุณพูดอาจรวมเข้ากับ VIM หรือตัวแก้ไขบรรทัดคำสั่งอื่น ๆ แต่ส่วนใหญ่มีปัญหาใหญ่

• IDEs ส่วนใหญ่สนับสนุนการยุบรหัส / ความคิดเห็นโดยผลลัพธ์สุดท้ายจะเป็นดังนี้:

  แทนที่จะเป็นเรื่องปกติ:

  

ทำให้โค้ดอ่านง่ายขึ้นในกรณีที่คุณไม่ต้องการความคิดเห็น

ซอร์สโค้ดและเอกสารประกอบในแบบที่ควรทำ

http://jasmine.github.io/2.3/introduction.html