READMEを始めとしたドキュメントは「ソフトウェアを理解する」ために作成されます。コードリーディングも「ソフトウェアを理解する」ために行う作業ですので、ドキュメントとの相性は良く、ぜひとも一緒に読み進めて理解を深めていきたいです。（参考：コードリーディングの補助としてドキュメントを読む）
しかし、読んだほうが良いとわかっていても、READMEを必ず読むようにしているという人は少ないのではないでしょうか？ コードリーディングのために READMEを積極的に読むという方はさらに少ないでしょう。
READMEを読まない理由の一つは、 有用な情報がどのくらいの時間や労力で得られるのかわからない ことです。なんとなく無駄な時間を過ごしてしまいそうな印象があります。そこで今回はOSSのREADMEを対象に、どのくらいの時間で読めそうなのかを調べてみました。
〇〇 mins readとは？
タイトルにも書きました「〇〇 mins read」は、記事の長さについての表記としてブログ等で用いられています。何分で読み切れるかという目安として使われます。
この表記を導入しているブログサービスのMedium によりますと、 英語記事の場合、1分あたり265ワード（単語） を目安にして記事の長さを読み切れる時間に換算しています1。 日本語、中国語、韓国語の場合は、1分あたり500語 が目安になっています。
注意が必要なのは、これらの目安は ネイティブの 平均速度であるという点です。日本人の英語力だと、センター試験レベルで1分あたり120-130ワード、TOEICのリーディングセクションを時間内に最後まで解き切れるレベルで1分あたり150ワード2だそうなので、これらの基準を自分にあてはめて換算するのが良いでしょう。
OSSのREADMEの長さ調査
OSSを適当にピックアップしてREADMEの長さを調査してみました。READMEのワード数、英語ネイティブの平均速度である1分あたり265ワードで計算した値に加えて、非ネイティブの速度を仮に1分あたり80ワードと換算した値も併記しました。
| OSS | language | words | mins | 換算値 |
|---|---|---|---|---|
| Node.js | JavaScript | 540 | 2 | 7 |
| Moment.js | JavaScript | 77 | 1 | 1 |
| terser | JavaScript | 7,066 | 27 | 89 |
| express | JavaScript | 437 | 2 | 6 |
| Puppeteer | TypeScript | 778 | 3 | 10 |
| Deno | TypeScript | 211 | 1 | 3 |
| Supabase | TypeScript | 666 | 3 | 9 |
| PyTorch | Python | 2,558 | 10 | 32 |
| Numpy | Python | 379 | 2 | 5 |
| Ruby on Rails | Ruby | 589 | 3 | 8 |
| Mastodon | Ruby | 533 | 2 | 7 |
| Phoenix LiveView | Elixir | 841 | 4 | 11 |
| Apache Log4j 2 | Java | 411 | 2 | 6 |
| syn | Rust | 1,295 | 5 | 17 |
まず READMEの長さがOSSによってかなりばらついている ことがわかります。ネイティブでも30分近くかけないと読みきれないような大作から、ほとんど有用な情報がないのではないかと思われるような簡素なものまで幅広かったです。確かにこれだけ分量にばらつきがあると、なんとなくREADMEを信用しすぎるのは危うい感じがします。
それでも 大半はネイティブの速度で5分以内、非ネイティブ換算でも10分以内に収まっています。この長さであれば、コードリーディングの前に有用な情報をいくつか仕入れておくためにREADMEを読んでもいいと思えるのではないでしょうか？ワード数を数えるのは手間なのでわざわざやらなくてもいいのですが、たとえばMastodonのREADMEを一度読んだことがあれば、それを基準として別のREADMEを読み切るのにどのくらいの時間がかかりそうであるかを判断できるでしょう。
1分あたり80ワードの換算値とネイティブの速度での計算値を比べると、READMEを読むことに対するネイティブの敷居の低さに驚きました。ほどほどの集中力で3分程度で読み切れるなら明らかに有利です。それでも＋5分でキャッチアップできるなら十分なメリットがあります。現実にめげずにREADMEを読んでいく癖をつけたいです。
実際にREADMEを読んでみた
調査したOSSのなかから、SupabaseとPhoenix LiveViewのREADMEを試しに読んでみました。いずれも名前くらいはどこかで見かけたことがあるという程度で事前情報はほとんど持ち合わせていませんでした。
結果は、Supabaseが6分、Phoenix LiveViewが8分かかりました。得られた情報は、そのOSSが何者であるかという基本情報とソフトウェアの動作や内部構造に関連するキーワードでした。Supabaseの場合は、複数のOSSを組み合わせて作られたFirebase代替プラットフォームという基本情報とこの構成を示した図や表によって全体像がつかめました。Phoenix LiveViewは、Elixirで書かれたRailsみたいなWebフレームワークという基本情報とサーバーサイドを中心としたサービスであるというコンセプトが理解できました。
いずれも コードリーディングを行う前に背景知識として補完できているとコードリーディングでのつまづきを減らすことができる という類の情報です。直接的なヒントや答えではないので軽視されがちですが、コードリーディング時の泥沼化を避けることは生産性を上げるために非常に重要です。目先の数分の時間短縮を狙うより、ドツボにはまって半日溶かしてしまうことを避けたほうが良いことは言うまでもありません。
今回調査したその他のOSSのREADMEのなかには、 短いながらも有用なドキュメントのリンク集として充実している ものが複数ありました。必要な情報がどこにあるのかをさっと短時間で把握するだけでも、十分な価値があると言えるでしょう。
おわりに
READMEの長さを調査して、コードリーディングに役立たせるためにどのくらいの時間を費やす必要があるのかを検証してみました。READMEの長さはまちまちですが、多くが10分程度で読み切れそうです。さっと目を通してキーワードを拾ったり、必要な情報がどこのページにあるのかを把握したりするだけでもコードリーディングの補助として役立つことでしょう。
コードリーディングが必要となる局面でさきにREADMEを読んでおこうという発想は浮かびにくいかもしれませんが、10分程度の時間をかけてREADMEを読むことで背景知識が得られ、コードリーディング時のつまづきを回避しやすくなります。READMEから完璧な知識を得ようとするのではなく、前提となっている情報を最初からおさえておくという目的で活用すれば、コードリーディングを円滑に進められるようになるでしょう。