今さらYARD + Solargraphで快適Rubyコーディング

世は Ruby 3.x で RBS わっしょい時代ですが、あえて今 YARD と Solargrpah の話。

目的

Ruby の開発でも JavaScript 並とは言わないまでもある程度カジュアルにエディタ / IDE の補完を利用し、TypeScript 並とは言わないまでも静的型の恩恵に与った、フィードバックが早くて安心感のある開発を行いたい。

結論

YARD + Solargraph ( + LSP ) でそれなりに快適になるのですぐやるべき。

案

Ruby で静的な型チェックを行う方法はいくつかあるが、今回は以下の二つを試した。

1. RBS + Steep
2. YARD + Solargraph

今回は RBI + Sorbet は試していない。これは以前（だいぶ前）試した¹ 時に native extension の挙動が変だった記憶があってちょっと苦手意識があるのと、RBI か RBS かで言うと Ruby 公式は Ruby 3.0 で RBS を採用しているので、手間を削減してツールや定義の充実を待つには RBS の方が有利という判断から。

比較

1. RBS + Steep

Ruby 2.6 以降で利用できる。

• ruby/rbs: Type Signature for Ruby
• ruby/gem_rbs_collection: A collection of RBS for gems.
• soutaro/steep: Static type checker for Ruby

よい点

• Ruby 本体の情報を含め、今後充実していくことが期待される
• 目的が明確に静的な検証であり、Union Type や Ruby にない Interface など、扱いやすい記述方法がある

イマイチな点

• Ruby 以外に RBS の文法を学習する必要がある
• まだまだ対応しているライブラリが少ない
• Steep に機能が足りないので漸進的な型付けをやりにくい
• RBS の導入方法などやや手順が多く複雑

2. YARD + Solargraph

Ruby 2.4 以降で利用できる。

• YARD - A Ruby Documentation Tool
• Solargraph: A Ruby Language Server
• Try Sord

よい点

• すでにある YARD ドキュメントをそのまま利用できるし、学習コストはかなり小さい
• ライブラリに関してはかなりの gem が YARD を利用しているので安心
• 設定手順が少ない
• ignore 設定もできるので完璧を目指さなくてよい
• ついでにドキュメントも充実させやすい
• Sord というツールで YARD から RBI / RBS を生成できるので、型検査を Steep / Sorbet などに移行することも可能

イマイチな点

• Ruby 本体は YARD 情報を持っていないので別途追加が必要だが、対応バージョンが少ないし、今後増える見込みも少ない
• ちょっと凝った定義を書こうとするとかなり独自の記法になってしまう（他の言語の経験も活かしにくい）

実際に試してみて

RBS + Steep はとにかくアレも足りないコレも足りないと怒られまくり、どんどん yak が増えていくのがつらい。あとインラインコメントのアノテーションが効いてるんだか効いてないんだかよく分からない。

対して Solargraph も CLI では typecheck にパスしてるのに VS Code extension 上ではエラー扱いになるものもあり、ネイティブで対応できる JavaScript に対していろいろちょっとずつ足りない感じになってしまう。保存して再起動するとエラーが消えていたりする。

ただ、トータルで言うと現時点で導入するには Solargraph の方が少ない負担で意図した効果を期待できる。YARD コメントでの型の記述力はやや物足りないが、RBS でも Ruby でよく使われるメタプログラミングには対応しきれていないので、それなら現実解としては Solargraph に軍配を上げざるを得ない。

結論として、テストを書く文化のあるアプリ開発の現場に type をすぐに導入したいという目的なら、2022-06 時点では Solargraph でよいと思う。ドキュメントも要るし。依存グラフとか、RBS への変換などアレコレ発展も望める。

個人的には、RBS についてはライブラリも含めてコミュニティに対するコントリビュートチャンスだなと思うので、ちまちま何かやりたいところ。

YARD + Solargraph 環境をよりよくするには

実際に導入するとなると gem の補完が効く嬉しさもあるが、自分たちのコードに対しても品質を確保し続けないと、書いたコードが増えれば増えるほど体験が悪くなっていってしまう。そこで利用したいのは以下。

• yard stats
• --list-undoc

ドキュメントが揃っているかどうかは stats サブコマンドで分かる。これは 100% をキープした方がよさそう。

どこの部分のドキュメントが足りないかは –list-undoc オプションを加えると分かる。例えば

yard stats --list-undoc 

を実行するとカバレッジとともに 100% を切った場合は不足している class やメソッドが列挙されるので、不足分をつぶしていけばよい。

新規にファイルを追加した場合にはうっかりカバレッジが不足する可能性も十分あるので、この yard stats の最終行が 100.00% documented でなくなったかどうかは CI で見ておいてもよいかもしれない。