มาเพิ่ม `ARCHITECTURE.md` กันเถอะ

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

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

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

  • หากไม่คุ้นเคยกับโครงสร้าง แม้เวลาในการเขียนแพตช์อาจเพิ่มขึ้นมากกว่า 2 เท่า แต่เวลาที่ใช้ในการหาว่าควรแก้ตรงไหนอาจมากขึ้นเกิน 10 เท่า

  • ให้เขียนไฟล์อย่าง ARCHITECTURE.md ที่อธิบายสถาปัตยกรรมระดับสูง

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

→ อย่าพยายามซิงก์กับโค้ดตลอดเวลา แต่กลับมาทบทวนใหม่ประมาณปีละ 2 ครั้ง

วิธีเขียนเนื้อหา

  • เริ่มจากภาพรวมของปัญหาที่ต้องการแก้ (Bird's eye view)

  • ตามด้วยแผนที่โค้ดที่ละเอียดขึ้นเล็กน้อย: "สิ่งที่ทำ X อยู่ตรงไหน?"

  • อธิบายโมดูลหลัก ๆ และความสัมพันธ์ระหว่างกัน: งานของแต่ละโมดูลให้เชื่อมไปยังเอกสารอื่น

  • ระบุชื่อของไฟล์ โมดูล และไทป์ที่สำคัญ

→ เพื่อให้ผู้อ่านค้นหาจากชื่อได้ และไม่ควรใส่ลิงก์ตรง ๆ (เพราะลิงก์อาจเสียได้)

  • ระบุขอบเขตระหว่างเลเยอร์และระบบต่าง ๆ ให้ชัดเจน
  • ตัวอย่างที่ดี

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

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

 
xguru 2021-02-08

และความเห็นที่ขอให้ใส่คำอธิบายของแต่ละโฟลเดอร์ของโปรเจ็กต์ไว้ใน README.md หลักด้วยถ้าเป็นไปได้ ก็ดีนะ

ตัวอย่าง: https://github.com/diem/diem/…

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

ในประเด็นที่เกี่ยวข้องกัน ลองดู Architecture Decision Records ด้วย