เอกสารสเปกทางเทคนิค "Architecture.md (2021)"

 (matklad.github.io)
1 คะแนน โดย GN⁺ 2024-02-26 | 1 ความคิดเห็น | แชร์ทาง WhatsApp

คำแนะนำในการเขียน ARCHITECTURE.md

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

เป้าหมายและความสำคัญของเอกสาร

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

โครงสร้างของเอกสาร

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

Invariants ทางสถาปัตยกรรมและขอบเขต

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

ประเด็นที่ครอบคลุมข้ามส่วน

  • หลังจากทำ codemap เสร็จแล้ว ควรเพิ่มส่วนแยกต่างหากสำหรับประเด็นที่ครอบคลุมข้ามส่วน
  • ตัวอย่างที่ดีของเอกสาร ARCHITECTURE คือ architecture.md ของ rust-analyzer

ความเห็นของ GN⁺:

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

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2024-02-26
ความคิดเห็นบน Hacker News

  • ขอแนะนำอย่างยิ่งให้เพิ่มเอกสาร ARCHITECTURE หากคุณดูแลโปรเจกต์โอเพนซอร์สและมีจำนวนบรรทัดโค้ดอยู่ระหว่าง 10k-200k

    • ไอเดียดี แต่คิดว่าสามารถใส่สถาปัตยกรรมไว้ใน Readme ได้โดยไม่ขึ้นกับขนาดของรีโพ ตัวอย่างเช่น ตั้งใจวาง Mermaid sequence diagram ไว้ใน Readme หลักเพื่อให้ผู้ใช้ทุกคนเข้าใจเวิร์กโฟลว์ได้

  • แนวทางนี้ยอดเยี่ยมในฐานะโมเดลที่ใช้การดูแลรักษาน้อยสำหรับโปรเจกต์โอเพนซอร์สที่มีผู้ร่วมพัฒนาแบบ ad hoc จำนวนมาก สำหรับโปรเจกต์ที่มีวิศวกรรับผิดชอบโดยเฉพาะ ควรพิจารณา ADRs สิ่งนี้ต้องการการดูแลรักษามากกว่า แต่มีประโยชน์มากเมื่อสร้างใหม่ เพราะบันทึกทั้ง "ทำไม" และ "ทางเลือกที่พิจารณาแล้ว"

  • เมื่อสองสามปีก่อนฉันเคยทดลองทำสิ่งคล้ายกันในหนึ่งในโปรเจกต์ข้างเคียงขนาดใหญ่ของฉัน:

    • ด้านบนของแต่ละไฟล์จะมีต้นไม้ลิงก์ไปยังไฟล์ ARCHITECTURE.md อื่น ๆ

  • IDE ทุกตัวแสดงโครงสร้างโฟลเดอร์ของโปรเจกต์ทางซ้ายด้วย directory tree มาตรฐาน มี IDE ตัวไหนบ้างที่รองรับการสำรวจโปรเจกต์ด้วย dependency graph?

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

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

    • อินเทอร์เฟซมีแนวโน้มเปลี่ยนน้อยกว่าและ [เปลี่ยนยากกว่า!] (Parnas, เกณฑ์ที่ใช้ในการแยกระบบออกเป็นโมดูล)

  • ในทุกโปรเจกต์ ฉันจะแสดงแผนภาพสถาปัตยกรรมและคำอธิบายสั้น ๆ ขององค์ประกอบต่าง ๆ ระหว่างการ onboarding

    • ตอนนี้แปลกใจว่าของแบบนี้หาได้ยากแค่ไหนในโลกโอเพนซอร์ส

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

  • ฉันเป็นแฟนของมาตรฐานเอกสาร/ไดอะแกรมแบบโค้ดเล็ก ๆ พวกนี้มาตลอด:

    • README-driven development
    • ARCHITECTURE.md
    • ADRs
    • arc42
    • C4
    • ฯลฯ
    • ตอนนี้ฉันใส่ Obsidian vault ไว้ในโฟลเดอร์ /docs ของ git repository
    • แทนที่จะใช้มาตรฐานของคนอื่น ฉันจัดระเบียบและรีแฟกเตอร์เอกสารเหมือนกับเวลาจัดการโน้ตส่วนตัวของตัวเองใน Obsidian
    • ฉันเคยพยายามใช้ Markdown ชุดย่อยร่วมกันที่ใช้ได้ทั้งใน GitHub (GFM) และ Obsidian แต่สุดท้ายก็เลิกและหันไปใช้ Markdown ของ Obsidian พร้อมฟีเจอร์เฉพาะของมัน
    • Obsidian มี Mermaid และ LaTeX ในตัว และมีปลั๊กอินสำหรับ PlantUML
    • สำหรับภาพ/ไดอะแกรมเชิงภาพ มี Canvas, DrawIO และ Excalidraw ติดตั้งมาในตัว

  • มีการพูดถึงเรื่องนี้ในตอนนั้น:

    • Architecture.md - Feb 2021 (153 ความคิดเห็น)