Tài liệu đặc tả kỹ thuật "Architecture.md (2021)"

Khuyến nghị viết ARCHITECTURE.md

• Khuyến nghị mạnh mẽ các maintainer dự án mã nguồn mở bổ sung tài liệu ARCHITECTURE bên cạnh README và CONTRIBUTING.
• Tài liệu này mô tả kiến trúc cấp cao của dự án, và nên giữ ngắn gọn vì những người đóng góp lặp lại sẽ cần đọc nó.
• Tài liệu ARCHITECTURE chỉ nên bao gồm những nội dung không thay đổi thường xuyên; thay vì cố đồng bộ với mã nguồn, tốt hơn là rà soát vài lần mỗi năm.

Mục đích và tầm quan trọng của tài liệu

• Kiến thức về kiến trúc vật lý của dự án là khác biệt lớn nhất giữa người đóng góp thông thường và nhà phát triển cốt lõi.
• Nếu chưa quen với dự án, sẽ mất gấp 2 lần thời gian để viết patch và gấp 10 lần thời gian để xác định cần sửa mã ở đâu.
• Tệp ARCHITECTURE là một cách hiệu quả để thu hẹp khoảng cách này, đồng thời cũng tạo cơ hội để nhìn lại cấu trúc của dự án.

Cấu trúc của tài liệu

• Nên bắt đầu bằng phần tổng quan từ một góc nhìn mới về vấn đề, rồi cung cấp một bản đồ mã nguồn chi tiết giải thích mối quan hệ giữa các module.
• Nên nêu rõ các tệp, module và kiểu dữ liệu quan trọng, nhưng thay vì liên kết trực tiếp thì khuyến khích tìm kiếm theo tên để không cần bảo trì liên kết.
• Cần chỉ rõ một cách tường minh các bất biến kiến trúc và các ranh giới giữa những tầng.

Bất biến kiến trúc và ranh giới

• Các bất biến quan trọng thường được biểu đạt bằng sự vắng mặt của một thứ gì đó, và chỉ đọc mã thì khó nhận ra điều này.
• Ranh giới giữa các tầng hoặc hệ thống ngầm chứa thông tin về cách hệ thống được triển khai, đồng thời ràng buộc mọi cách triển khai khả dĩ.

Mối quan tâm xuyên suốt

• Sau khi hoàn thành bản đồ mã nguồn, nên thêm một mục riêng cho các mối quan tâm xuyên suốt.
• Một ví dụ hay về tài liệu ARCHITECTURE là architecture.md của rust-analyzer.

Ý kiến của GN⁺:

• Tài liệu ARCHITECTURE đóng vai trò quan trọng trong việc hỗ trợ hiểu dự án và giúp người đóng góp mới nhanh chóng làm quen với codebase.
• Tài liệu này làm rõ cấu trúc dự án, nhấn mạnh các nguyên tắc và ranh giới kiến trúc quan trọng để giúp nhà phát triển hiểu hệ thống tốt hơn.
• Việc áp dụng tài liệu ARCHITECTURE trong cộng đồng mã nguồn mở có thể góp phần vào tăng trưởng bền vững và bảo trì dự án, và đây là một cách tiếp cận rất hữu ích cũng như thú vị với các nhà phát triển.

[GN⁺]

Ý kiến Hacker News

• Nếu bạn đang quản lý một dự án mã nguồn mở và số dòng code nằm trong khoảng 10k-200k, tôi rất khuyến nghị thêm tài liệu ARCHITECTURE.

  • Ý tưởng này hay, nhưng tôi nghĩ có thể đưa kiến trúc vào Readme bất kể kích thước của kho lưu trữ. Ví dụ, tôi cố tình đặt sơ đồ chuỗi Mermaid trong Readme chính để mọi người dùng đều có thể hiểu quy trình làm việc.

• Cách tiếp cận này rất phù hợp như một mô hình ít cần bảo trì đối với các dự án mã nguồn mở có nhiều người đóng góp ad hoc. Với các dự án có kỹ sư phụ trách chuyên trách, nên cân nhắc ADRs. Cách này đòi hỏi bảo trì nhiều hơn, nhưng việc ghi lại "lý do" và "các phương án đã được cân nhắc" rất hữu ích khi tái cấu trúc.

• Vài năm trước tôi đã thử một thứ tương tự trong một trong những dự án phụ lớn của mình:

  • Ở đầu mỗi tệp có một cây liên kết tới các tệp ARCHITECTURE.md khác.

• Mọi IDE đều hiển thị cấu trúc thư mục của dự án ở bên trái dưới dạng cây thư mục tiêu chuẩn. Có IDE nào hỗ trợ duyệt dự án bằng đồ thị phụ thuộc không?

• Cần cẩn trọng khi mở rộng điều tác giả viết ở đây sang các dự án phần mềm nói chung. Với các dự án mã nguồn mở lớn có nhiều người đóng góp nhưng ít ngữ cảnh, việc duy trì loại tài liệu này rất đáng giá. Nhưng trong các dự án nhỏ ở công ty, mọi tài liệu do lập trình viên viết mà tôi từng thấy cuối cùng đều không còn được duy trì.

• Tài liệu càng ngắn thì càng ít có khả năng bị những thay đổi trong tương lai làm cho mất hiệu lực. Đây là quy tắc chính của tài liệu ARCHITECTURE — chỉ ghi rõ những thứ ít có khả năng thay đổi thường xuyên. Đừng cố đồng bộ nó với code.

  • Giao diện thì ít có khả năng thay đổi hơn và [khó hơn nhiều!] (Parnas, tiêu chí dùng để phân rã hệ thống thành các mô-đun).

• Trong mọi dự án, khi onboarding tôi đều cho xem sơ đồ kiến trúc và phần mô tả ngắn về các thành phần của nó.

  • Giờ tôi ngạc nhiên vì điều này hiếm đến vậy trong mã nguồn mở.

• Đây là một thực hành rất hữu ích. Nhiều dự án có một vài tệp cốt lõi (hoặc package/module/v.v.) nơi phần lớn thay đổi diễn ra. Nếu giúp những người đóng góp mới (hoặc những người quay lại sau thời gian dài) nhanh chóng nắm được chúng, có thể rút ngắn đáng kể thời gian bắt đầu tham gia dự án.

• Tôi từng là người rất thích các chuẩn sơ đồ nhỏ gọn dạng tài liệu/code như thế này:

  • README-driven development
  • ARCHITECTURE.md
  • ADRs
  • arc42
  • C4
  • v.v.
  • Giờ tôi đặt một Obsidian vault trong thư mục /docs của kho git.
  • Thay vì dùng chuẩn của người khác, tôi tổ chức và tái cấu trúc tài liệu giống như cách quản lý ghi chú cá nhân trong Obsidian.
  • Tôi đã cố dùng một tập con Markdown chung hoạt động cả trên GitHub (GFM) lẫn Obsidian, nhưng cuối cùng bỏ cuộc và dùng Markdown của Obsidian cùng các tính năng riêng của nó.
  • Obsidian có tích hợp Mermaid và LaTeX, và có plugin cho PlantUML.
  • Để vẽ hình/sơ đồ trực quan, có sẵn Canvas, DrawIO, Excalidraw.

• Đã được thảo luận khi đó:

  • Architecture.md - Tháng 2 năm 2021 (153 bình luận)