Hãy thêm ARCHITECTURE.md

 (matklad.github.io)
26 điểm bởi xguru 2021-02-08 | 1 bình luận | Chia sẻ qua WhatsApp

  • Bài viết đề xuất thêm vào repo một tệp mô tả kiến trúc của dự án để việc tham gia mã nguồn mở trở nên dễ dàng hơn

  • Khác biệt lớn nhất giữa người thỉnh thoảng đóng góp cho dự án và nhà phát triển cốt lõi là mức độ hiểu biết về kiến trúc của dự án

  • Nếu không quen với cấu trúc, thời gian viết bản vá có thể mất hơn gấp đôi, nhưng thời gian để xác định phải sửa ở đâu còn mất nhiều hơn gấp 10 lần

  • Hãy viết một tệp như ARCHITECTURE.md để giải thích kiến trúc ở mức độ cao

→ Viết ngắn để ai cũng có thể đọc được, chỉ tổng hợp những phần không thay đổi nhiều

→ Đừng cố đồng bộ với mã nguồn, thay vào đó hãy xem lại khoảng 2 lần mỗi năm

Cách viết nội dung

  • Bắt đầu bằng cái nhìn tổng quan (Bird's eye view) về vấn đề đang muốn giải quyết

  • Bản đồ mã nguồn chi tiết hơn một chút: "Phần làm X nằm ở đâu?"

  • Giải thích sơ lược các mô-đun và mối quan hệ giữa chúng: việc mỗi mô-đun làm gì thì liên kết sang tài liệu khác

  • Hãy ghi tên các tệp, mô-đun, kiểu dữ liệu quan trọng

→ Để người đọc có thể tìm kiếm theo tên, và không nên gắn liên kết trực tiếp (vì có thể bị hỏng)

  • Nêu rõ ranh giới giữa các lớp và các hệ thống
  • Ví dụ tốt

Bài viết liên quan

1 bình luận

 
xguru 2021-02-08

Và ý kiến đề nghị nếu có thể thì thêm phần giải thích về từng thư mục của dự án vào README.md chính cũng rất hay.

Ví dụ: https://github.com/diem/diem/…

Nếu có thể thì nên thêm mô tả cho từng thư mục, và sẽ rất tốt nếu GitHub có thể hiển thị nội dung đó từ cấp trên khi trong thư mục có README.

Ngoài ra, hãy tham khảo cả Architecture Decision Records.