esbuild và Redis, hai dự án mã nguồn mở có tài liệu kiến trúc xuất sắc

 (johnjago.com)
27 điểm bởi GN⁺ 2024-03-26 | 2 bình luận | Chia sẻ qua WhatsApp
  • esbuild và Redis là những ví dụ về các codebase có tài liệu hóa xuất sắc.
  • Thông qua README, changelog, tài liệu kiến trúc và chú thích trong mã, ngay cả người dùng mới cũng có thể hiểu được cấu trúc của codebase, cách nó hoạt động và lý do đằng sau.
  • Đây là những nghiên cứu điển hình tốt cho các lập trình viên muốn cải thiện việc tài liệu hóa mã và kiến trúc phần mềm.

Vì sao tài liệu tốt lại quan trọng

  • Khi viết phần mềm, tài liệu tốt là điều thiết yếu, đặc biệt khi người khác xem hoặc đóng góp vào codebase, hoặc khi chính bạn cần tham chiếu lại sau này.
  • Người dùng phần mềm thường gặp khó khăn vì tài liệu bị thiếu sót.
  • Nếu bạn đóng góp vào một codebase, chất lượng tài liệu càng tốt thì bạn càng có thể đóng góp nhanh hơn.
  • Chất lượng tài liệu ảnh hưởng trực tiếp hoặc gián tiếp đến trải nghiệm của tác giả, người đóng góp và người dùng.
  • Lợi ích của tài liệu tốt rất đa dạng: tiết kiệm thời gian, tăng đóng góp từ bên ngoài cho các dự án mã nguồn mở, lưu lại các quyết định trong quá khứ, giúp nhiều người dùng tiếp cận hơn, cấu trúc hóa tư duy và phát hiện vấn đề.

Tài liệu của esbuild

  • esbuild là một JavaScript bundler do Evan Wallace tạo ra.
  • README của esbuild tập trung vào người dùng cuối của công cụ.
  • Thông qua các liên kết đến những phần chính trong tài liệu và mục "Tại sao?", README giải thích ngắn gọn vì sao nên chọn esbuild thay vì các bundler khác.
  • Tài liệu kiến trúc của esbuild gồm các tệp architecture.md và development.md trong thư mục docs.
  • Tài liệu kiến trúc giải thích các nguyên tắc thiết kế và không chỉ có văn bản mà còn bao gồm đồ họa minh họa các khái niệm.
  • Changelog của esbuild rất chi tiết, bao gồm tóm tắt, phần giải thích mở rộng và mã ví dụ trước/sau thay đổi.

Tài liệu của Redis

  • Redis là một cơ sở dữ liệu in-memory.
  • README của Redis chia sẻ nhiều đặc điểm tốt tương tự README của esbuild, đồng thời tập trung vào cả người đóng góp lẫn người dùng cuối.
  • Phần nói về nội bộ của Redis bao gồm bố cục của mã nguồn và phần giải thích về các tệp chính.
  • Các chú thích trong mã nguồn Redis cung cấp phần giải thích kéo dài nhiều đoạn cho chỉ một dòng mã.

Kết luận

  • Nhiều dự án mã nguồn mở có tài liệu rất xuất sắc.
  • esbuild và Redis đặc biệt gây ấn tượng nhờ chất lượng tài liệu nổi bật.
  • Việc viết tài liệu có thể tạo ra áp lực thời gian trong ngắn hạn, nhưng về lâu dài lại giúp tiết kiệm thời gian.
  • Với những dự án có nhiều người sử dụng hoặc đóng góp, việc không làm tài liệu là điều cần được cân nhắc lại.

Ý kiến của GN⁺

  • Các ví dụ tài liệu của esbuild và Redis nhấn mạnh tầm quan trọng của tài liệu trong việc giúp lập trình viên dễ hiểu và bảo trì codebase hơn.
  • Tài liệu là yếu tố cốt lõi giúp nâng cao tính bền vững của dự án và thúc đẩy sự tham gia của cộng đồng.
  • Với esbuild, ngoài vai trò là một JavaScript bundler tốc độ cao, tài liệu xuất sắc dường như cũng góp phần vào sự phát triển của dự án.
  • Redis tạo ảnh hưởng tích cực đến cộng đồng lập trình viên nhờ tài liệu giúp họ dễ hiểu một hệ thống cơ sở dữ liệu in-memory phức tạp.
  • Những ví dụ này cũng có thể giúp lan tỏa tầm quan trọng của tài liệu đến các dự án mã nguồn mở khác, và đặc biệt hữu ích trong việc giúp các kỹ sư phần mềm mới vào nghề hiểu cách tài liệu hóa dự án của mình.

Bài viết liên quan

2 bình luận

 
laeyoung 2024-03-29

esbuild thì khỏi nói đến file README.md, nhưng file architecture.md được giới thiệu trong bài cũng đẹp một cách đáng kinh ngạc!
 
GN⁺ 2024-03-26
Ý kiến Hacker News

  • Antirez, người sáng lập Redis, đã viết một bài trên blog của mình giải thích chi tiết suy nghĩ về chú thích trong mã. Ông xác định 9 loại chú thích được sử dụng trong Redis.

    • Nhiều người ngạc nhiên về việc sử dụng "chú thích hướng dẫn", loại mà họ cho là không quan trọng.
    • Antirez kết luận rằng những chú thích này có giá trị trong việc giúp hiểu mã nguồn.
    • Bài viết của Antirez

  • Một bài viết được viết tốt, có các ví dụ cụ thể và ảnh chụp màn hình về cách tài liệu dự án có thể trở nên xuất sắc đối với người dùng/nhà phát triển/người đóng góp.

    • Nó khiến người đọc suy ngẫm về công việc và các dự án phụ của chính mình, cũng như cách cải thiện tài liệu để hỗ trợ việc hiểu.
    • Khi trưởng thành hơn với tư cách nhà phát triển, người ta có xu hướng viết nhiều tài liệu và bài kiểm thử hơn. Một số dự án thậm chí có nhiều tài liệu và kiểm thử hơn cả mã nguồn thực tế.
    • Có ý kiến cho rằng viết tài liệu tốt đòi hỏi một bộ kỹ năng khác với viết mã. Đôi khi một người không quá kỹ thuật hoặc không tập trung vào phát triển lại có thể giải thích tốt hơn.
    • Tài liệu được tạo tự động cũng có thể hữu ích, không chỉ đứng riêng mà còn có giá trị như tài liệu tham khảo bổ sung.

  • Điều này cho thấy những người quản lý dự án quan tâm đến chất lượng của kho mã.

  • Nó gợi nhớ đến loạt "The Architecture of Open Source Applications". Có nhiều góc nhìn thú vị.

  • GitLab có tiếng là có tài liệu rất tốt, nhưng người bình luận chưa từng cần dùng trực tiếp nhiều. Họ tự hỏi liệu tài liệu kiến trúc của GitLab có tốt không.

  • Dự án Postgres cũng rất chú ý đến tài liệu, các tệp readme và chú thích trong mã.

  • Người bình luận rất ấn tượng với tài liệu kiến trúc của dự án esbuild. Họ ước những codebase mình từng làm việc trước đây cũng có loại tài liệu như vậy.

    • Họ hỏi thêm về các ví dụ dự án khác có mức độ tài liệu hóa kiến trúc như thế này.

  • Người bình luận rất thích changelog của các dự án mã nguồn mở. Chúng chuyên nghiệp và giàu thông tin hơn nhiều so với các thực thể khác theo đuổi lợi nhuận. Có lời phê bình rằng changelog ứng dụng của ngân hàng ING nên tập trung cung cấp thông tin thay vì cố gắng hài hước.

  • "Thiếu hụt lớn nhất trong cộng đồng phần mềm tự do ngày nay không phải là phần mềm, mà là sự thiếu vắng tài liệu tự do tốt có thể đi kèm với phần mềm tự do."

    • Trích dẫn từ sổ tay gdb.

  • Có nhắc rằng Redis không còn là mã nguồn mở nữa. Redis là phần mềm "source-available", theo giấy phép Redis Source Available License v2 (RSALv2) và Server Side Public License v1 (SSPLv1).

    • Redis Stack và mọi mô-đun Redis do Redis Ltd. tạo ra (ví dụ: RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, RedisBloom) được cấp phép kép theo RSALv2 và SSPL.
    • Redis Enterprise là mã nguồn đóng và cần giấy phép thương mại từ Redis Ltd.
    • Các phiên bản Redis trước đây dùng giấy phép BSD 3-clause (tự do và mã nguồn mở). Việc thay đổi giấy phép không có hiệu lực hồi tố, và toàn bộ mã nguồn cùng các bản phát hành trước thời điểm thay đổi vẫn giữ nguyên giấy phép BSD 3-clause ban đầu. Miễn là tuân thủ các điều kiện đó, có thể sử dụng các phiên bản này vô thời hạn.
    • Giấy phép Redis
    • Giấy phép BSD