มีเหตุผลใดบ้างในการสร้างเอกสารรหัสโดยอัตโนมัติ [ปิด]

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

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

ในที่สุดมันสามารถสร้างเอกสารแปลกประหลาดที่ทำให้เข้าใจผิดในความพยายามที่จะเข้าใจความหมายของชื่อ:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

มันดูเหมือนว่าทัศนคติที่มี GhostDoc คือ "มันเป็นพื้นฐานที่ดีกว่าที่จะมีชนิดของเอกสาร XML อย่างเป็นทางการ" แต่เมื่อเอกสารที่เป็น 100% ซ้ำซ้อนทำไม? มันเป็นการสูญเสียพื้นที่ที่ดีที่สุดใช่ไหม

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

[... ] บันทึกทุกอย่างและเกือบจะตลอดเวลาด้วยเอกสารที่สร้างขึ้นโดยอัตโนมัติของ GhostDoc คุณทำเช่นนี้และมีเหตุผลใดที่จะไม่ทิ้งรหัสไว้หากคุณไม่ได้เขียนเอกสารด้วยตัวเองจริง ๆ หรือไม่?

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

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

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

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

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

มีเหตุผลใดบ้างในการสร้างเอกสารรหัสโดยอัตโนมัติ

จากมุมมองของใคร

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

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

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

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

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

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

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

คำตอบเดิม: เหตุใดการแยกและจัดรูปแบบเอกสารอัตโนมัติจึงเป็นความคิดที่ดี

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

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

สิ่งนี้ยังช่วยให้เราใช้เครื่องมือเดียวในการสร้างทั้ง "ทฤษฎีการดำเนินงาน" ซึ่งอธิบายรหัสฐานทั้งหมดของเราและ "บันทึกย่อประจำรุ่น" หลายชุดที่อธิบายผลิตภัณฑ์ซอฟต์แวร์ แต่ที่จริงแล้วไม่มีเอกสาร "รหัส" จริง ๆ ใน ความรู้สึกทั่วไป

สำหรับสาเหตุที่เราต้องการเอกสารที่ไม่ใช่ซอร์สโค้ดเกี่ยวกับพฤติกรรมของรหัสของเรามีสองเหตุผล:

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

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

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

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

ดังนั้นใช่การสร้างเอกสารอัตโนมัติจะเพิ่มคุณค่าบางอย่าง แน่นอนไม่มากเท่าที่ผู้จัดการอาจสันนิษฐานและมักจะไม่มากเท่าที่คัดลอกสำเนาที่ดีจริง ๆ จะ แต่ไม่มีอะไร

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

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

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

จากประสบการณ์นั้นคำตอบของคำถามคือ: ใช่ แต่เราต้องการเครื่องมือที่ชาญฉลาดกว่ามาก

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

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

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

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

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

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

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

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

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

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

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

สุดท้าย (และสำคัญมากสำหรับฉัน) มันลบค่าใช้จ่ายที่ไม่สำคัญในการเขียนทั้งหมดออกไปและพยายามทำให้ทันสมัยอยู่เสมอเมื่อ coders (อ่านจำนวนมาก) กระทำการเปลี่ยนแปลงและไม่คุยกับผู้ดูแลเอกสาร

ดังนั้นเหตุผลรวมถึง:

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

นอกจากนี้อย่าประมาทค่าของการรักษาผู้บังคับบัญชาที่มีผมหงอกอย่างมีความสุขเพียงแค่กดปุ่ม

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

มันมักจะดีที่จะใช้เครื่องกำเนิดเอกสารเพื่อสร้างความคิดเห็นสำเร็จรูปหรือ "ยืนใน" ที่มีการแก้ไขในภายหลังโดยนักพัฒนาจริง ฉันมักจะใช้ฟังก์ชั่น auto-JavaDoc ของ Eclipse เพื่อสร้างความคิดเห็นส่วนหัวด้วยประเภทพารามิเตอร์และค่าส่งคืนที่กรอกไว้แล้วจากนั้นก็เพิ่ม "เนื้อ" ของเอกสาร

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

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

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

หลีกเลี่ยง Tautology

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

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

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

ไม่ใช่ทุกสิ่งที่ควรจัดทำเป็นเอกสารด้วยตนเอง

สิ่งต่างๆเช่นเมธอด getXXX / setXXX ควรเป็นคำอธิบายด้วยตนเองดังนั้นเอกสารสร้างอัตโนมัติที่ช่วยให้คุณรู้ว่ามีอยู่จะได้รับการตอบรับดี

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

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

ผู้ใช้ที่มีความซับซ้อนน้อยที่สุดจะไม่เห็นคุณค่าด้วยเหตุผลที่ตรงกันข้าม พวกเขาไม่เข้าใจมันเลย

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

คำตอบง่ายๆสำหรับ "ทำไมสร้างเอกสาร" สามารถตอบได้อย่างง่ายดายโดยแสดง MSDN

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

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

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

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