จะดีกว่าการทำเอกสารฟังก์ชั่นในไฟล์ส่วนหัวหรือไฟล์ต้นฉบับ?

ในภาษาที่แยกความแตกต่างระหว่างไฟล์ "แหล่งที่มา" และ "ส่วนหัว" (ส่วนใหญ่ C และ C ++) จะดีกว่าฟังก์ชั่นเอกสารในไฟล์ส่วนหัวหรือไม่:

(ขโมยจากCCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

หรือในไฟล์ต้นฉบับ?

(ขโมยจาก PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

โปรดทราบว่าบางสิ่งมีการกำหนดไว้ในส่วนหัวเท่านั้นเช่น structs, macros และstatic inlineฟังก์ชั่น ฉันแค่พูดถึงสิ่งที่ประกาศในไฟล์ส่วนหัวและกำหนดไว้ในไฟล์ต้นฉบับ

นี่คือข้อโต้แย้งที่ฉันสามารถนึกได้ ฉันกำลังเอนไปยังการจัดทำเอกสารในไฟล์ต้นฉบับดังนั้นข้อโต้แย้ง "Pro-header" ของฉันอาจค่อนข้างอ่อนแอ

Pro-ส่วนหัว:

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

Pro-แหล่งที่มา:

• มันทำให้ส่วนหัวสั้นลงมากทำให้ผู้อ่านมองเห็นมุมมองของโมดูลโดยรวม
• มันจับคู่เอกสารของฟังก์ชั่นกับการใช้งานทำให้ง่ายขึ้นที่จะเห็นว่าฟังก์ชั่นทำในสิ่งที่มันบอกว่ามันทำ

เมื่อตอบคำถามโปรดระวังข้อโต้แย้งโดยพิจารณาจากเครื่องมือและ "โมเดิร์นไอดี" ที่สามารถทำได้ ตัวอย่าง:

• Pro-header: การพับโค้ดสามารถช่วยให้ส่วนหัวที่มีความคิดเห็นสามารถนำทางได้มากขึ้นโดยการซ่อนความคิดเห็น
• Pro-source: คุณลักษณะของcscopeFind this global definitionจะนำคุณไปยังไฟล์ต้นฉบับ (โดยนิยามคือ) แทนที่จะเป็นไฟล์ส่วนหัว (โดยที่การประกาศคือ)

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

มุมมองของฉัน...

• เอกสารวิธีใช้ฟังก์ชันในไฟล์ส่วนหัวหรือใกล้เคียงกับการประกาศอย่างแม่นยำมากขึ้น

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

สำหรับสิ่งที่น่าสนใจในส่วนหัวคุณไม่จำเป็นต้องใช้เอกสารที่ปิด - คุณสามารถจัดทำเอกสารกลุ่มการประกาศพร้อมกันได้

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

หากคุณกำลังจะใช้เครื่องมือเช่นDoxygen (หมายเหตุในตัวอย่างแรกที่ดูเหมือนว่าความคิดเห็น Doxygen เพราะมันเริ่มต้นด้วย/**) มันไม่สำคัญเลย - Doxygen จะมองผ่านไฟล์ส่วนหัวและแหล่งที่มาของคุณและค้นหา ความคิดเห็นทั้งหมดเพื่อสร้างเอกสาร

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

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

เราแก้ไขปัญหานี้ (ประมาณ 25 ปีที่แล้ว) โดยการสร้าง #defines (เช่นสาธารณะส่วนตัว ฯลฯ ที่แก้ไขเป็น <ไม่มี>) ที่สามารถใช้ในไฟล์ต้นฉบับและถูกสแกนโดย awk script (น่ากลัว !) เพื่อสร้างไฟล์. h โดยอัตโนมัติ ซึ่งหมายความว่าความคิดเห็นทั้งหมดอาศัยอยู่ในแหล่งที่มาและถูกคัดลอก (ตามความเหมาะสม) ลงในไฟล์. h ที่สร้างขึ้น ฉันรู้ว่ามันเป็นโรงเรียนเก่า แต่มันทำให้เอกสารแบบอินไลน์แบบนี้ง่ายขึ้นอย่างมากมาย

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

• ส่วนหัว:
  แสดงความคิดเห็นสั้น ๆ 1-2 บรรทัดเฉพาะเมื่อจำเป็นเท่านั้น
  บางครั้งความคิดเห็นด้านบนกลุ่มของฟังก์ชันที่เกี่ยวข้องก็มีประโยชน์เช่นกัน
• ที่มา:
  เอกสารเกี่ยวกับ API โดยตรงเหนือฟังก์ชั่น(ข้อความธรรมดาหรือ Doxygen ถ้าคุณต้องการ)
• เก็บรายละเอียดการใช้งานเฉพาะที่เกี่ยวข้องกับนักพัฒนาที่แก้ไขโค้ดในเนื้อความของฟังก์ชัน

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

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

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

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

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

แต่นั่นเป็นเพียงฉัน ...

ความคิดเห็นไม่ใช่เอกสารประกอบ โดยทั่วไปแล้วเอกสารสำหรับฟังก์ชั่นอาจเป็นข้อความ 2K หรืออาจเป็นไดอะแกรมดูตัวอย่างเอกสารสำหรับฟังก์ชั่นใน Windows SDK แม้ว่า comment-to-doc ของคุณจะอนุญาตสิ่งนี้คุณจะต้องสร้างรหัสที่มีความคิดเห็นที่อ่านไม่ได้ หากคุณต้องการผลิตเอกสารใช้ word-processor

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

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

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