สิ่งที่ฉันควรรวมไว้ในส่วนหัวของเอกสารประกอบการเรียน

ฉันกำลังมองหารูปแบบเอกสารข้อมูลระดับสำหรับ Entity, Business Logic และคลาส Data Access ของฉัน

ฉันพบรูปแบบสองรูปแบบจากที่นี่

รูปแบบ 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

รูปแบบ 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

ฉันรู้สึกว่าต่อไปนี้เป็นองค์ประกอบพื้นฐาน

• ผู้เขียน
• วันที่สร้าง
• ลักษณะ
• ประวัติการแก้ไข

ในชื่อ Namespace และ Class จะมีอยู่ในนั้น

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

ข้อมูลส่วนใหญ่ที่คุณแนะนำมีอยู่ในแหล่งเก็บข้อมูล

สิ่งเดียวที่คุณต้องการจริงๆคือส่วนของจุดประสงค์ซึ่งระบุสิ่งที่ชั้นเรียนมีให้

ทุกครั้งที่คุณอยากรู้ข้อมูลอื่น ๆ จะต้องดูน่าเบื่อมั้ย ฉันจะบอกว่าไม่ คุณสนใจผู้แต่งต้นฉบับคนนั้นบ่อยแค่ไหน หรือเมื่อไฟล์ถูกสร้างขึ้นครั้งแรก? ปลั๊กอิน (เช่น Ankh SVN สำหรับ Visual Studio) มักจะอนุญาตให้คุณคลิกขวาภายในไฟล์ปัจจุบันของคุณและดูบันทึก repoistory สำหรับไฟล์ดังนั้นจึงไม่ใช่เรื่องยากที่จะเห็นข้อมูลนี้

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

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

อ่านบทความนี้โดยเจฟฟ์แอด - การเข้ารหัสโดยไม่ต้องแสดงความคิดเห็น

ฉันใช้แท็กมาตรฐานเพื่อสร้างเอกสาร ไม่มีอะไรเพิ่มเติมไม่น้อยไปกว่านี้ ดูที่นี่

ฉันไม่เคยใส่ข้อมูลที่ไม่ได้อยู่ในชั้นเรียน ผู้เขียนข้อมูลการแก้ไขเป็นข้อมูลที่จะเก็บไว้ในระบบควบคุมเวอร์ชัน

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

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

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

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

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

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

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

คำตอบอื่น ๆ ส่วนใหญ่ที่ฉันอ่านมาสันนิษฐานว่ามีพื้นที่เก็บข้อมูลเดียวเท่านั้นที่พร้อมใช้งานเสมอ

เนื่องจากซอร์สโค้ดสามารถหลวมการเชื่อมต่อไปยังที่เก็บ (เช่นถ้าคัดลอก) เอกสารประกอบการเรียนของฉันเป็นแบบนี้:

• class documentation header (= บล็อกความคิดเห็นที่จุดเริ่มต้นของไฟล์) มีเฉพาะข่าวสารทางกฎหมายที่จำเป็นเท่านั้น (เช่นลิขสิทธิ์โดย xyz ภายใต้ใบอนุญาต gpl)
• ทุกสิ่งที่นักพัฒนาที่ใช้คลาสควรรู้ควรเข้าไปใน class-java-doc-comments (หรือ. net ที่เทียบเท่า) เพื่อให้ modern ide-s สามารถแสดงข้อมูลนี้เป็นแหล่งข้อมูลคำแนะนำเครื่องมือที่ใช้คลาส

คุณยังสามารถเพิ่ม ticketnumber สำหรับ bugfix หรือฟีเจอร์ - request ดังนั้นคุณอาจมีเงื่อนงำที่ / เมื่อ / ทำไมคลาสถูกสร้างขึ้น (ถ้าคุณโชคดีพอที่คุณยังสามารถเข้าถึงตั๋วหลังจากไม่กี่ปี)

เมื่อ beeing ขอให้แก้ไขปัญหาในโปรแกรมรุ่นเก่าที่มาแบบปิดต้นฉบับรหัสตั๋วซึ่งค่อนข้างมีค่าสำหรับฉันที่จะเข้าใจความต้องการดั้งเดิมของรหัส