Ruby on Railsを使った開発で参照してもよいドキュメント

記事中のURLや内容、特にRailsやRubyのバージョンについて古くなっていることに気づいた方はぜひ編集リクエストください。

---

この記事はOkinawa.rbのAdventCalendar 5日目の記事です。

YassLabの業務時間中にQiita:Teamに書き溜めたものを編集して公開します。

4日目は @siman さんの「今年作った gem の紹介 (2017)」でした。
明日は @fullkawa さんのFinOpsのはなしです。

背景

人数が増えたり参加プロジェクトが増えるにつれ以下のような変化がおきました。

• 同じソフトウェアのさまざまなバージョンを扱うようになった
• コードレビューをする人・される人が増えた

同じソフトウェアでもバージョンによってAPIや使い方が異なる場合があります。
また、人によっては参考にする情報源がバラバラになってしまい、ソフトウェアの開発者が提供しているドキュメントやバージョンのあったドキュメントよりもGoogleの検索結果の上位に表示されているウェブページや、更新日時の古い記事、書かれている内容が不安な記事を参考にしてしまう問題がおきました。

なので、開発者間でのソフトウェアのドキュメントの探し方の指針をある程度示し、コードレビューの際に参考にするに足る信頼できるドキュメントの探し方・読み方を共有しました。

ドキュメントを参考にする際の心構え

ドキュメントもソフトウェアも人が書いているものなので間違いはあります。
ドキュメントを参考にする際は、ドキュメントで書かれているような動作をするのか実際に手元で確認しましょう。

またソフトウェアのバージョンによってドキュメントの内容も変わってきます。
かならずバージョンを確認するようにしましょう。

ruby

ruby-lang.orgには各種チュートリアルやリファレンスマニュアルなどのドキュメントへのリンク集があります。
https://www.ruby-lang.org/en/documentation/
https://www.ruby-lang.org/ja/documentation/

バージョンごとのドキュメントが読みたければ以下のページからアクセスすると良いです。
https://docs.ruby-lang.org/en/
https://docs.ruby-lang.org/ja/

rubyのリファレンスを調べる前に以下のようなコマンドで自分が使っているrubyのバージョンを確認して、使っているrubyのバージョンに合ったマニュアルを読みましょう。

$ ruby -v
ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-linux]

Ruby on Rails

Ruby on Railsの場合、以下のようなドキュメントがあります。

Ruby on Rails API
Ruby on Rails Guides

使い分けとして、ざっくりとした概念の説明や使い方はRuby on Rails Guidesを参考にし、個別のメソッドの使い方や細かなオプションを調べたい場合はRuby on Rails APIで調べるとよいです。

Ruby on Railsも読む前にかならずバージョンを確認しましょう。

$ bin/rails -v
Rails 5.1.4

Ruby on Railsの場合、以下のようにURLの末尾にバージョン番号がついたURLから各バージョンに対応したドキュメントを読めます。

Ruby on Rails Guides

• https://edgeguides.rubyonrails.org/
• https://guides.rubyonrails.org/
• https://guides.rubyonrails.org/v6.0/
• https://guides.rubyonrails.org/v5.2/
• https://guides.rubyonrails.org/v5.1/
• https://guides.rubyonrails.org/v5.0/
• https://guides.rubyonrails.org/v4.2/

Ruby on Rails API

• https://api.rubyonrails.org/
• https://api.rubyonrails.org/v6.0/
• https://api.rubyonrails.org/v5.2/
• https://api.rubyonrails.org/v5.1/
• https://api.rubyonrails.org/v5.0/
• https://api.rubyonrails.org/v4.2/

RSpec

以下からrdocで書かれたAPIとRelishのドキュメントをたどれます。
http://rspec.info/documentation/

普通にRuby on Railsでアプリケーション開発をしていてテストで使うマッチャ―の書き方などを調べたいのであればRelishの方を読むとよいです。
https://relishapp.com/rspec

APIの方はRSpec関連のgemを開発する際に使えるような細かい情報まで載っています。

RSpecもバージョンを確認して、お使いのRSpecに合ったバージョンのドキュメントを読むようにしましょう。バージョンは以下のように確認できます。

$ bundle exec rspec -v
RSpec 3.7
  - rspec-core 3.7.0
  - rspec-expectations 3.7.0
  - rspec-mocks 3.7.0
  - rspec-rails 3.7.2
  - rspec-support 3.7.0

gemのドキュメント

基本的には以下の流れで確認できます。

1. RubyGemsでgemのなまえを入力して検索しgemのページを開く
2. Show all versionsをクリックして開く
3. 使っているバージョンをクリックして開く
4. 右側のLINKSからDocumentationを開く

ただしrubygemsからは正しいドキュメントが確認できない場合があります。
その場合、gemのホームページを開き、READMEなどからそのバージョンにあったドキュメントを探します。

最終的に開いたドキュメントのURLにバージョンが含まれているかどうかが重要です。使っているgemのバージョンと合っているか必ず確認しましょう。現在使用しているgemのバージョンは以下のようなコマンドで確認できます。

$ bundle exec gem list | grep ここに調べたいgemの名前を書く

例: Turnipの場合

1. turnipで検索して出てきたgemのページを開く
   https://rubygems.org/gems/turnip

2. Show all versionsをクリック
   https://rubygems.org/gems/turnip/versions

3. 使っているバージョンをクリックして開く
   https://rubygems.org/gems/turnip/versions/3.0.0

4. 右側のDocumentationを開く
   http://www.rubydoc.info/gems/turnip/3.0.0

例: ActiveModel::Serializerの場合

active_model_serializersの場合、前述した方法で0.8.4のページを開いても
https://rubygems.org/gems/active_model_serializers/versions/0.8.4

以下のように最新版のドキュメントへのリンクになってしまい、対応するバージョンのドキュメントのページにたどり着けません。
http://www.rubydoc.info/gems/active_model_serializers

その場合はgemのHomepageへとびREADMEの内容を読み解いていきます。
https://github.com/rails-api/active_model_serializers

active_model_serializersの場合はREADMEのDocumentationの項目から各バージョンへのリンクがはられています。
https://github.com/rails-api/active_model_serializers#documentation

無事ドキュメントにたどり着くことができました。
https://github.com/rails-api/active_model_serializers/tree/0-8-stable

補足: GitHubからドキュメントを探す方法

タグが切られているソフトウェアの場合、GitHubのリポジトリからタグを選択するとそのバージョン時点のリポジトリの内容が確認できます。「Branch」をクリックして「tags」のタブからタグを選びましょう。

タグが切られていないソフトウェアの場合、バージョン番号が書かれているファイルのコミット履歴を辿ってリビジョンを特定しましょう。

ソフトウェアのリポジトリ(GitHub)

コードレビューでは開発中のWebアプリケーションのソースコードを参照することも多いです。

GitHubで指定した行へのリンクを貼る場合、URLにタグが含まれるようにタグを選択しましょう。タグがない場合、ショートカットのyを押してCanonicalなURLに変更しましょう。

https://help.github.com/articles/getting-permanent-links-to-files/

いい例: タグで参照する

Switch branches/tagsでtagに切り替えてからURLを貼ります。タグは基本的に変更しないので常に同じ内容を参照できます。

いい例: permanentなURLで参照する

キーボードショートカットのyを押すと参照している時点のコミットハッシュ値がURLに含まれます。コミットハッシュ値は変らないので常に同じ内容を参照できます。

悪い例: ブランチ名で参照する

以下のようなURLは貼ったタイミングでは意図した内容がハイライトされていても、後からみたときにハイライトされている内容が変わる可能性があります。
https://github.com/yasslab/vue-control-picture/blob/master/index.js#L7-L11

例えば、masterブランチでindex.jsのL7〜L11の内容が変更されたとき、ハイライトされる内容が変わってしまいます。
またファイル自体が削除されたりリネームされた場合、404になってしまいます。

悪い例のリンクが404になっていたり位置がずれていそうだがどうしても読みたい場合

gitでリポジトリをcloneして、git logの--sinceオプションや--untilオプションでリンクが投稿された時点のコミットを探し、checkoutして確認する。

しかし --since や --until のような時間制限のオプションは非常に便利です。たとえばこのコマンドは、過去二週間のコミットの一覧を取得します。
https://git-scm.com/book/ja/v1/Git-の基本-コミット履歴の閲覧

JavaScriptやウェブブラウザ関連技術

JavaScriptなどWeb開発の周辺技術についてはMDNを見ます。
https://mdn.mozilla.org/ja/

MDNを見る理由

MicrosoftやGoogleやW3CやSamsungなどが協力して作っています。
https://blog.mozilla.org/blog/2017/10/18/mozilla-brings-microsoft-google-w3c-samsung-together-create-cross-browser-documentation-mdn/

技術仕様書

同じなまえでも別々の団体から発行されていることがあります。どの仕様が要求されているのか確認すること。

例: ECMA-404とrfc7159のように複数の団体がJSONについて別々に仕様を公開している

IETFが出してるRFC

新しいRFCが出てobsoletedになっていることがあります。気をつけましょう。

例: JSONのRFCはrfc4627, rfc7158, rfc7159がある

W3Cが出してる文書

draftやeditionに気をつけましょう

本

本の場合も他のドキュメントと同様に対象バージョンと出版年月日に気をつけましょう。
コードレビューなどで引用する際は後から確認しなおせるよう

• 書名
• 版
• 章番号
• ページ数

などを必ず明記しておきましょう。

ソフトウェアのウェブサイトで紹介されている本

The RSpec Bookのようにそのソフトウェアのウェブサイト上で紹介されている本がないか確認しましょう。
http://rspec.info

著者がソーシャルメディアやQiitaで積極的に活動している本

著者にフィードバックをおくりやすく、著者からのフィードバックが得られる可能性があります。

コミュニティ情報

以下は必ず確認することを書いていきます。

ソフトウェアのバージョン

記事にかかれているソフトウェアのバージョンを確認してください。
バージョンの違いによっては動かない可能性があります。

情報の信頼性

信頼できる情報源の情報のみ参考にしましょう。
何を信頼するかはあなた次第ですが、ソフトウェアは人間が書いているものなので、信頼出来る人が増えれば信頼出来る情報も増えます。

理解しないままコードやコマンドを実行しない

コードやコマンドを実行する前に 書かれているコードやコマンドやコマンドのオプションをソフトウェアのマニュアルやドキュメント等で再度確認し、全て理解した上で実行すること。

理解しないまま実行すると危険なコマンドはいっぱいあります。

参考: 【試さないで】危険シェル芸【違法(脱法)シェル芸を勧められたり、 身近な人が持っていたりしませんか？】 - Togetterまとめ

記事中のコードのライセンス

ライセンスが不明なコードは使わないようにしましょう。

具体的にコミュニティ情報とは

例えば以下のような情報です。

• 会話
• ブログ記事
• Qiita上にある記事
• Twitterのツイート

特にTwitterはかなり便利で、以下のように検索するとTwitter上の有益な情報がてにはいります(ただし過激な発言が多くて参考リンクとしてはりづらいことが多い)。

1. Rubyistをフォロー
2. gemのなまえで検索
3. 検索の設定で「People you follow」に変更

ドキュメントを読むコマンド

bundlerを使っている場合、bundle exec riやbundle exec rdocのように、それぞれのコマンドを実行する際にbundle execで実行するよう読み替えてください。bundlerでインストールしたgemにパスが通ってうまく動くようになります。

ri

riコマンドを使うとローカルにインストールされているrubyやgemのドキュメントを読むことができます。

% ri itself
= .itself

(from ruby core)
=== Implementation from Object
------------------------------------------------------------------------------
  obj.itself -> an_object

------------------------------------------------------------------------------

Returns obj.

  string = 'my string' #=> "my string"
  string.itself.object_id == string.object_id #=> true

refe

日本語のRubyリファレンスマニュアル、るりまのドキュメントを検索できます。

$ gem i refe2
$ bitclust setup
$ refe itself
Object#itself
--- itself -> object

self を返します。

 string = 'my string' # => "my string"
 string.itself.object_id == string.object_id # => true

gem server

gem server コマンドを使うとインストールされているgemのrdocのドキュメントを閲覧できます。

% gem help serverから引用

Description:
The server command starts up a web server that hosts the RDoc for your
installed gems and can operate as a server for installation of gems on other
machines.

以下のようにgem serverコマンドを実行してサーバーを立ち上げます。

% gem server
Server started at http://[::]:8808
Server started at http://0.0.0.0:8808

表示されているURLにアクセスします。
http://0.0.0.0:8808

redisをクリックします。

rdocがリンクになっていない場合 gem rdoc コマンドでrdocを生成します。

% gem rdoc redis
Parsing documentation for redis-3.3.0
Installing ri documentation for redis-3.3.0

rdocのリンクをクリックするとドキュメントが読めます。

以下のような感じで表示されるので、必要なメソッドやクラスのリンクからたどる。

コマンドに付属しているヘルプやマニュアル

コマンドの使い方がわからないときはコマンド自身に聞きましょう。
ほとんどのコマンドは-h/--helpオプションでヘルプを表示できます。

$ ruby -h
Usage: ruby [switches] [--] [programfile] [arguments]
  -0[octal]       specify record separator (\0, if no argument)
  -a              autosplit mode with -n or -p (splits $_ into $F)
  -c              check syntax only
  -Cdirectory     cd to directory before executing your script
  -d              set debugging flags (set $DEBUG to true)
  -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
  -Eex[:in]       specify the default external and internal character encodings
  -Fpattern       split() pattern for autosplit (-a)
  -i[extension]   edit ARGV files in place (make backup if extension supplied)
  -Idirectory     specify $LOAD_PATH directory (may be used more than once)
  -l              enable line ending processing
  -n              assume 'while gets(); ... end' loop around your script
  -p              assume loop like -n but print line also like sed
  -rlibrary       require the library before executing your script
  -s              enable some switch parsing for switches after script name
  -S              look for the script using PATH environment variable
  -T[level=1]     turn on tainting checks
  -v              print version number, then turn on verbose mode
  -w              turn warnings on for your script
  -W[level=2]     set warning level; 0=silence, 1=medium, 2=verbose
  -x[directory]   strip off text before #!ruby line and perhaps cd to directory
  -h              show this message, --help for more info

より詳しい内容を確認したい場合は以下のようにmanコマンドでマニュアルを読みましょう

$ man ruby

実践例: プロジェクトで使っているソフトウェアのバージョンにあったドキュメントのURLをピンして貼っておく

プロジェクトに入ったタイミングで使っているソフトウェアのドキュメントへのリンク集を作っておくと見に行く手間が省けて便利です。

ドキュメントがない場合

ドキュメントが用意されていないソフトウェアは使うのを避けましょう。

ドキュメントがない場合

ドキュメントを書きましょう。

まとめ

ドキュメント最高! みんな書こう。