ドキュメントの先へ:GitHubコード検索でライブラリの使い方を実例から学ぶ

新しいライブラリや機能を使い始めたものの、ドキュメントを読んでもいまいち理解できない——そんな経験はありませんか?セットアップが難しくてRDocを行き来しながら全体像を掴む羽目になったり、そもそもドキュメントがほとんど存在しなかったりすることもあります。あるいは、実際のコード例をたくさん見ることで初めて腹落ちするタイプの人かもしれません。

助けは必要です。しかし、ドキュメント以外のどこで機能の使い方を学べばいいのでしょうか?

お気に入りのGitHub機能

ドキュメントの先へ進んで、ライブラリや機能が現実のプロジェクトでどう使われているのかを見たいときは、GitHubのコード検索を活用しましょう。

たとえば、Railsガイドの「Conditional GET Support」を読み終えた直後だとします。内容はなんとなく理解できた気がするけれど、実際に使う前にもう少し例を目にしたい——そんな場面です。

具体的には、GitHubの検索バーで "if stale?" と入力して検索し、サイドバーのフィルタで種類を code(コード)、言語を Ruby に絞ります。これだけで、世界中のオープンソースプロジェクトから該当するコード片が一覧表示されます。

すると、stale? の優れた使用例が大量に見つかるのです。

すべての例が参考になるわけではありません。しかし、その中の一つで、ある作者が Post.maximum を組み合わせていることに気づきました。

class ArchivesController < ApplicationController
  def index
    if stale?(last_modified: (Post.maximum(:updated_at) || EPOCH).utc, public: true)
      @months = Post.find_all_grouped_by_month
    end
  end
end

これは stale? の非常にスマートな使い方に見えます。この例に出会っていなければ、自分では思いつかなかった可能性が高いでしょう。

見つけたコードはどう活用すべきか?

オープンソースのコードを検索すれば、ほぼあらゆる機能について何百もの実例が手に入ります。ドキュメントのどこが的確で、どこが単純化されすぎているのかが見えてきますし、実際のコードの中でオブジェクト同士がどう連携しているのかも確認できます。クラス間のつながりについては、どんなRDocを読むよりも多くのことを学べるはずです。

ただし、見つけた例は「新しいことを学ぶための材料」として使うべきであり、そのまま自分のプロジェクトへ持ち込む(いわゆるカーゴ・カルト的にコピーする)ためのものではありません。理解せずにコードを使うことは、設計の悪いシステムを作る最短ルートです。

先ほどの例で言えば、maximum が自分のプロジェクトにとって正しい選択だとは限りません。詳細を調べずにその行をコピーすべきではありませんし、どんな状況で使うのが妥当なのかを理解した上で判断する必要があります。それでも、実例はこれまで知らなかった書き方や考え方を教えてくれる貴重な情報源です。「次に何を学ぶべきか」を決める指針としても最適です。

他の検索と同じように、質の高い結果を得るには多少の慣れが必要です。それでも、私はこの方法で見つけたコードから多くのことを学んできました。きっとあなたにとっても、ドキュメントだけでは得られない発見があるはずです。