YT: microsoft/codetour

2021-05-01

だいぶ時間が空いてしまいましたが、コードリーディング中のメモなどを残しておける VisualStudio Code の拡張である CodeTour を触ったときのことを振り返ります。

YouTube

(音が良くないな…)

returntocorp/semgrep

https://github.com/microsoft/codetour

why?

ちょうどMessage Passing で DesignDoc に関する記事が書かれてたりしたので、ドキュメンテーションに関することに興味が向いていました。(Message Passing は色んな人の思考が漏れ出てる感じで好き)

そんなとき(おそらく HackerNews の Tweet から)CodeTour のことを知り、ある程度の量のあるコードを読むときの入り口となるドキュメントとして使えそうだなと思い、触ってみようと思いました。

what?

VS Code 上で各ファイルの行単位でコメントを残すことができ、後からコメントを残したところだけを辿っていけるというもの。Intro.jsのエディタ版という感じですかね。

コメントは直接ファイルに書くわけではなく、.tours配下にメタデータとして記録されます。JSON 形式で記録できるので、Git の履歴管理に載せることもでき、Tour に関連する箇所に変更があった時にそれを検知するための GitHub Action なども用意されているようです。

https://github.com/microsoft/codetour#maintaining-tours

How?

Install

VS Code の拡張機能なので、Marketplace からインストールするだけ。

https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour

インストールするところ。 https://youtu.be/M-3xfnP4hRo?t=601

Execute

インストールが完了した後、VS Code の左サイドバーに CODETOUR というメニューが追加されているのでメニューを開き、+を押してレコーディングを開始します。レコーディングを開始した後は、VS Code 上でファイルを開くと、行番号の横に + マークが表示されるようになるため、そこをクリックするとツアーの内容を記述するウィンドウが現れます。

https://youtu.be/M-3xfnP4hRo?t=752

ツアー内容はCodeTour Flavored Markdownという Markdown 拡張で記述することができます。CodeTour Flavored Markdown のうち、一番興味深かったのは　Shell Commandsの機能。>> に続いてコマンドを記述しておくと、閲覧時はリンク文字列として表示され、そのリンクをクリックするとコマンドが実行されるというもの。テストコードの説明にテスト実行コードを埋め込んでおくなどすると、すぐにコードが実行できて便利そう。

https://youtu.be/M-3xfnP4hRo?t=1484

Impression

コードコメントをツアーという形で記録できる VS Code 拡張。ドキュメントとして書くとコードと乖離するし、コードコメントとして書くと俯瞰しづらくなるし、というコードにまつわるドキュメンテーションの課題に対して良いところを付いている感じがした。コメントが散在するためメンテナンスしづらいという点については、CI で変更を検出するという手段も用意しているところ、抜け目ないなという印象。自動で更新してくれるともっと嬉しいけど、変更後の位置の Tracking は、それはそれで困難なので仕方ない（別ファイルへの移動をどう扱うか、とか）。

CodeTour-Flavored-Markdown まで作ってたり、ドキュメントもしっかり書いてあるので肝入りのプロジェクトという感じがする。

と、着眼点も素晴らしいし、プロダクトとしても完成度は高そうだけど、気になるのは誰が使うのかというところかな。案内が必要なほど大きなプロジェクトは関わる人数も多く、それぞれに守備範囲も違うだろうし、その中で統一した CodeTour を記述するには専任の人を付けなきゃ記述粒度などの統一性がすぐに取れなくなくなることは容易に想像できる。しかし、専任を付けるほどの価値を提供できるかというと、細部を知りたい初学者はそう多くはないだろうから専任付けるだけのメリットはなさそう。OSS で不特定多数に向けて公開してたとしても、コード触り始める初学者は、要求があって触り始めてるわけで CodeTour があろうがなかろうが読むでしょという感じがする。

面白いプロダクトではあるけど、使い続けるイメージはあまりわかなかったかな。あまり動きの少ない SI プロジェクトとかの方がむしろ合うのかも。

Contribute

ない。