esbuild และ Redis: สองโปรเจกต์โอเพนซอร์สที่มีเอกสารสถาปัตยกรรมยอดเยี่ยม

 (johnjago.com)
27 คะแนน โดย GN⁺ 2024-03-26 | 2 ความคิดเห็น | แชร์ทาง WhatsApp
  • esbuild และ Redis เป็นตัวอย่างของโค้ดเบสที่มีการจัดทำเอกสารได้ยอดเยี่ยม
  • ผ่าน README, changelog, เอกสารสถาปัตยกรรม และคอมเมนต์ในโค้ด แม้แต่ผู้ใช้ใหม่ก็สามารถเข้าใจโครงสร้างของโค้ดเบส วิธีการทำงาน และเหตุผลเบื้องหลังได้
  • นับเป็นกรณีศึกษาที่ดีสำหรับนักพัฒนาที่ต้องการปรับปรุงการจัดทำเอกสารของโค้ดและสถาปัตยกรรมซอฟต์แวร์

ทำไมเอกสารที่ดีจึงสำคัญ

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

เอกสารของ esbuild

  • esbuild เป็น JavaScript bundler ที่สร้างโดย Evan Wallace
  • README ของ esbuild มุ่งเน้นไปที่ผู้ใช้งานปลายทางของเครื่องมือ
  • ผ่านลิงก์ไปยังหัวข้อหลักของเอกสารและส่วน "ทำไม?" จึงอธิบายอย่างกระชับว่าทำไมควรเลือก esbuild แทน bundler อื่น
  • เอกสารสถาปัตยกรรมของ esbuild อยู่ในไดเรกทอรี docs โดยประกอบด้วยไฟล์ architecture.md และ development.md
  • เอกสารสถาปัตยกรรมอธิบายหลักการออกแบบ และไม่ได้มีแค่ข้อความเท่านั้น แต่ยังมีกราฟิกที่ช่วยอธิบายแนวคิดด้วย
  • changelog ของ esbuild มีรายละเอียดมาก โดยมีทั้งสรุป คำอธิบายเพิ่มเติม และตัวอย่างโค้ดก่อน-หลังการเปลี่ยนแปลง

เอกสารของ Redis

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

บทสรุป

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

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

  • กรณีศึกษาด้านเอกสารของ esbuild และ Redis ตอกย้ำถึงความสำคัญของเอกสารที่ช่วยให้นักพัฒนาเข้าใจและดูแลโค้ดเบสได้ง่ายขึ้น
  • เอกสารเป็นองค์ประกอบสำคัญที่ช่วยเพิ่มความยั่งยืนของโปรเจกต์และส่งเสริมการมีส่วนร่วมของชุมชน
  • ในกรณีของ esbuild นอกจากความสามารถในฐานะ JavaScript bundler ที่รวดเร็วแล้ว เอกสารที่ยอดเยี่ยมก็ดูจะมีส่วนช่วยให้โปรเจกต์เติบโตด้วย
  • Redis สร้างผลกระทบเชิงบวกต่อชุมชนนักพัฒนาด้วยเอกสารที่ช่วยให้ระบบฐานข้อมูลในหน่วยความจำที่ซับซ้อนเข้าใจได้ง่ายขึ้น
  • กรณีเหล่านี้สามารถช่วยเผยแพร่ความสำคัญของเอกสารไปยังโปรเจกต์โอเพนซอร์สอื่น ๆ และมีประโยชน์อย่างยิ่งต่อวิศวกรซอฟต์แวร์ระดับเริ่มต้นในการทำความเข้าใจวิธีจัดทำเอกสารสำหรับโปรเจกต์ของตนเอง

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

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

 
laeyoung 2024-03-29

esbuild ไม่ใช่แค่ไฟล์ README.md เท่านั้น แต่ไฟล์ architecture.md ที่แนะนำในบทความก็ยอดเยี่ยมมากเช่นกัน!
 
GN⁺ 2024-03-26
ความคิดเห็นจาก Hacker News

  • Antirez ผู้ก่อตั้ง Redis ได้เขียนบทความในบล็อกของเขาอธิบายแนวคิดเกี่ยวกับคอมเมนต์ในโค้ดไว้อย่างละเอียด โดยระบุคอมเมนต์ 9 ประเภทที่ใช้ใน Redis

    • หลายคนรู้สึกประหลาดใจกับการใช้ "คอมเมนต์นำทาง" ซึ่งมักถูกมองว่าไม่สำคัญ
    • Antirez สรุปว่าคอมเมนต์เหล่านี้มีคุณค่าในการช่วยให้เข้าใจโค้ดได้ดีขึ้น
    • บทความของ Antirez

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

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

  • แสดงให้เห็นว่าผู้ดูแลให้ความสำคัญกับคุณภาพของ repository

  • ชวนให้นึกถึงชุด "The Architecture of Open Source Applications" ซึ่งมีมุมมองที่น่าสนใจ

  • GitLab มีชื่อเสียงว่าเอกสารดีมาก แต่ยังไม่เคยจำเป็นต้องใช้งานโดยตรงมากนัก จึงสงสัยว่าเอกสารสถาปัตยกรรมของพวกเขาดีหรือไม่

  • โปรเจ็กต์ Postgres ก็ใส่ใจรายละเอียดของเอกสาร ไฟล์ readme และคอมเมนต์ในโค้ดอย่างมากเช่นกัน

  • ประทับใจกับการทำเอกสารสถาปัตยกรรมของโปรเจ็กต์ esbuild มาก และรู้สึกว่าถ้าโค้ดเบสที่เคยทำงานด้วยในอดีตมีเอกสารแบบนี้ก็คงดี

    • ถามหาตัวอย่างโปรเจ็กต์อื่น ๆ ที่มีการทำเอกสารสถาปัตยกรรมในระดับนี้

  • ชอบบันทึกการเปลี่ยนแปลงของโปรเจ็กต์โอเพนซอร์สมาก เพราะดูเป็นมืออาชีพและให้ข้อมูลมากกว่าเอนทิตีอื่นที่มุ่งหากำไร พร้อมวิจารณ์ว่า changelog ของแอป ING Bank ควรเน้นให้ข้อมูลมากกว่าจะพยายามทำให้ตลก

  • "สิ่งที่ขาดแคลนมากที่สุดในชุมชนซอฟต์แวร์เสรีทุกวันนี้ไม่ใช่ซอฟต์แวร์ แต่คือการขาดเอกสารเสรีที่ดีซึ่งสามารถแนบไปกับซอฟต์แวร์เสรีได้"

    • อ้างอิงจากคู่มือ gdb

  • มีการกล่าวถึงว่า Redis ไม่ใช่โอเพนซอร์สอีกต่อไป โดย Redis เป็นซอฟต์แวร์แบบ "source-available" ภายใต้ Redis Source Available License v2 (RSALv2) และ Server Side Public License v1 (SSPLv1)

    • Redis Stack และ Redis modules ทั้งหมดที่ Redis Ltd. สร้างขึ้น (เช่น RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, RedisBloom) ใช้การให้สิทธิ์แบบ dual license ภายใต้ RSALv2 และ SSPL
    • Redis Enterprise เป็นซอฟต์แวร์ปิดซอร์ส และต้องมี commercial license จาก Redis Ltd.
    • Redis เวอร์ชันก่อนหน้านี้อยู่ภายใต้สัญญาอนุญาต 3-clause BSD (เสรีและโอเพนซอร์ส) การเปลี่ยนสัญญาอนุญาตไม่มีผลย้อนหลัง และซอร์สโค้ดกับรีลีสทั้งหมดก่อนการเปลี่ยนแปลงยังคงใช้สัญญาอนุญาต 3-clause BSD เดิม ตราบใดที่ปฏิบัติตามเงื่อนไข ก็สามารถใช้เวอร์ชันเหล่านี้ได้ตลอดไป
    • สัญญาอนุญาตของ Redis
    • สัญญาอนุญาต BSD