esbuildとRedis、優れたアーキテクチャ文書を備えた2つのオープンソースプロジェクト

 (johnjago.com)
27 ポイント 投稿者 GN⁺ 2024-03-26 | 2件のコメント | WhatsAppで共有
  • esbuildとRedisは、優れたドキュメントを備えたコードベースの好例である
  • README、変更ログ、アーキテクチャ文書、コードコメントを通じて、新しいユーザーでもコードベースの構造、動作方法、そしてその理由を理解できる。
  • コードとソフトウェアアーキテクチャの文書化を改善したい開発者にとって、良いケーススタディとなる。

優れた文書化が重要な理由

  • ソフトウェアを書く際、とくに他の人がコードベースを見たり貢献したりするときや、後で自分自身が再び参照するときには、優れた文書化が不可欠である。
  • ソフトウェアの利用者は、文書化の不足によってしばしば苦労する。
  • コードベースに貢献する場合、文書化の質が高いほど、より速く貢献できる。
  • 文書化の質は、作者、貢献者、利用者の体験に直接的または間接的に影響する。
  • 優れた文書化の利点には、時間の節約、オープンソースプロジェクトへの外部貢献の増加、過去の意思決定の記録、より多くの利用者にとってのアクセスしやすさ、思考の構造化や問題点の発見などがある。

esbuildの文書化

  • esbuildはEvan Wallaceが作ったJavaScriptバンドラーである。
  • esbuildのREADMEは、ツールのエンドユーザーに焦点を当てている。
  • 文書の主要セクションへのリンクと「なぜ？」というセクションを通じて、他のバンドラーではなくesbuildを選ぶべき理由を簡潔に説明している。
  • esbuildのアーキテクチャ文書は、docsディレクトリ内のarchitecture.mdとdevelopment.mdファイルで構成されている。
  • アーキテクチャ文書は設計原則を説明し、テキストだけでなく概念を説明する図も含んでいる。
  • esbuildの変更ログは、要約、拡張説明、変更前後のサンプルコードを含み、詳細である。

Redisの文書化

  • Redisはインメモリデータベースである。
  • RedisのREADMEは、esbuildのREADMEと同様の優れた特徴を共有しつつ、貢献者とエンドユーザーの両方に焦点を当てている。
  • Redisの内部に関するセクションには、ソースコードのレイアウトと主要ファイルの説明が含まれている。
  • Redisのソースコード内のコードコメントは、単一のコード行に対して複数段落にわたる説明を提供している。

まとめ

  • 多くのオープンソースプロジェクトは優れた文書化を備えている。
  • esbuildとRedisは、とくに優れた文書化によって印象的である。
  • 文書化は短期的には時間的制約を生むことがあるが、長期的には時間の節約につながる。
  • 多くの人が利用または貢献するプロジェクトで文書化を行わないことは、再考する必要がある。

GN⁺の見解

  • esbuildとRedisの文書化の事例は、コードベースの理解と保守を容易にする文書化の重要性を開発者に強調している。
  • 文書化は、プロジェクトの持続可能性を高め、コミュニティ参加を促進する中核的な要素である。
  • esbuildの場合、高速なJavaScriptバンドラーとしての機能に加え、優れた文書化がプロジェクトの成長に寄与したように見える。
  • Redisは、複雑なインメモリデータベースシステムを理解しやすくする文書化によって、開発者コミュニティに前向きな影響を与えている。
  • こうした事例は、他のオープンソースプロジェクトにも文書化の重要性を広める助けとなり、とくに初級ソフトウェアエンジニアが自分のプロジェクトをどのように文書化すべきかを理解するうえで有用である。

関連記事

2件のコメント

 
laeyoung 2024-03-29

esbuild は README.md ファイルもそうですが、記事で紹介されている architecture.md ファイルがとても素晴らしいですね！
 
GN⁺ 2024-03-26
Hacker Newsのコメント

  • Redisの創始者であるAntirezが、自身のブログでコードコメントに関する考えを詳しく説明した記事を書いている。Redisで使われている9種類のコメントを特定している。

    • 多くの人が重要ではないと考える「ガイドコメント」の使用に驚いた。
    • Antirezは、こうしたコメントがコード理解を助けるうえで価値があると結論づけている。
    • Antirezの記事

  • プロジェクトのドキュメントがユーザー／開発者／コントリビューターにとってどのように優れたものになりうるかについて、具体例やスクリーンショットを交えて書かれた良質な記事。

    • 自分の仕事やサイドプロジェクトについて振り返らせ、理解を助けるためにドキュメントをどう改善できるかを考えさせられる。
    • 開発者として成長するにつれて、より多くのドキュメントやテストを書くようになった。実際のコードよりドキュメントやテストのほうが多いプロジェクトもある。
    • 良いドキュメントを書くには、コードを書くのとは異なるスキルセットが必要だという意見がある。時には、技術者ではなかったり開発に集中していなかったりする人のほうが説明がうまいこともある。
    • 自動生成されたドキュメントも有用であり、それ単体だけでなく追加の参考資料として価値がある。

  • リポジトリの品質に対するメンテナーたちの関心がうかがえる。

  • 「The Architecture of Open Source Applications」シリーズを思い出させる。興味深い洞察がある。

  • GitLabのドキュメントは非常に良いという評判があるが、自分では直接使う機会があまりなかった。彼らのアーキテクチャ文書も良いのか気になる。

  • Postgresプロジェクトも、ドキュメント、readmeファイル、コードコメントに細やかな注意を払っている。

  • esbuildプロジェクトのアーキテクチャ文書化に深く感銘を受けた。過去に携わったコードベースにもこうした文書があればよかったと思う。

    • このレベルのアーキテクチャ文書化を備えた他のプロジェクトの例はあるか、という問い。

  • オープンソースプロジェクトの変更ログがとても好きだ。営利目的の他の組織のものよりはるかにプロフェッショナルで有益だ。ING銀行のアプリの変更ログは、ユーモアを狙うより情報提供に集中すべきだという批判。

  • 「今日の自由ソフトウェアコミュニティにおける最大の欠落はソフトウェアではなく、自由ソフトウェアと一緒に配布できる優れた自由ドキュメントの不足である。」

    • gdbマニュアルからの引用。

  • Redisはもはやオープンソースではないことへの言及。RedisはRedis Source Available License v2 (RSALv2) と Server Side Public License v1 (SSPLv1) の下にある「ソース利用可能」ソフトウェアである。

    • Redis Stackと、Redis Ltd.が作成したすべてのRedisモジュール（例: RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, RedisBloom）は、RSALv2とSSPLのデュアルライセンスとなっている。
    • Redis Enterpriseはクローズドソースであり、Redis Ltd.からの商用ライセンスが必要である。
    • 以前のバージョンのRedisは、3-clause BSDライセンス（自由かつオープンソース）の下にある。ライセンス変更は遡及適用されず、変更前のすべてのソースコードとリリースは元の3-clause BSDライセンスのままである。該当条件を守る限り、これらのバージョンは無期限に利用できる。
    • Redisライセンス
    • BSDライセンス