blog | ikuma-t.com

「こんにちは TAG-さん!」とは何か

2024/5/4

に公開

こんにちは TAG-さん!

https://github.com/w3ctag/design-reviews/issues🔗

W3C Technical Architecture Group が保有する design-reviews というリポジトリでは、新しい仕様に対するレビューが GitHub Issue で行われています。

直近の Issue のすべてが「こんにちは TAG-さん! 」で始まっており、なぜ突然日本語が出てくるのか不思議に思ったので調査することにしました。

調査結果

この挨拶文は ISSUE TEMPLATE に含まれている。
W3C TAG では定期的に Face to Face Meeting を行っており、その開催地に合わせて挨拶文が変わる。
ただし厳密な運用はしておらず、「こんにちは TAG-さん!」は 2023 年 04 月に開催された東京での MTG に合わせたもの。

調査詳細

Issue template を確認する

全員同じ始まりということはおそらくテンプレートがそういう形式なのだろうということで、確認したところ、確かにテンプレートに「こんにちは TAG-さん! 」の文字列が含まれていました。

https://github.com/w3ctag/design-reviews/blob/main/.github/ISSUE_TEMPLATE/005-early-design-review.md?plain=1#L11🔗

https://github.com/w3ctag/design-reviews/blob/main/.github/ISSUE_TEMPLATE/010-specification-review.md?plain=1#L11🔗

https://github.com/w3ctag/design-reviews/blob/main/.github/ISSUE_TEMPLATE/020-dispute-escalation.md?plain=1#L10🔗

ISSUE TEMPLATE は 3 種類あります。

template 名	内容
005-early-design-review	初期段階での方向性について考えやガイダンスを提供してほしい場合に使用
010-specification-review	現在取り組んでいる Web 技術の仕様についてレビューしてもらいたいの場合に使用
020-dispute-escalation-review	現在の論争について意見を求める場合に使用

Issue template の起源

https://github.com/w3ctag/design-reviews/commit/68a1436aa797b7b30002a5ec39f4ce1dfa451942🔗

git blame すると、2019年05月23日にこのテンプレートが作成されたことがわかります。ここを確認すると、この時点で「こんにちはTAG!」（現在は「こんにちは TAG-さん!」）という文字列が含まれていることがわかりました。

作成された際のコミットメッセージは次のとおりであり、もともと「specification review」というテンプレートがどこか（メーリングリストとか？）にあったことが伺えます。

Create issue templates in the new format Make issue templates in the new format. Use the existing template as a “specification review” template, and create a somewhat different template for “dispute resolution”.

なお Issue Template をこのリポジトリに作成した人物は Google に勤めるエンジニアの L. David Baron さんです。

https://github.com/dbaron🔗

もっと！Issue template の起源

現在の Issue Template はここまでしか辿れませんが、日付と過去に別のテンプレートがあった、という情報が手に入ったので、リポジトリ全体の History を参照してみました。

すると、2019年05月09日に ISSUE_TEMPLATE.md を変更しているコミットを発見。

https://github.com/w3ctag/design-reviews/commit/426a9a8b3fc6314deb9f44a60ade76d2edaca6fd🔗

このファイルの履歴を辿ってみます。

https://github.com/w3ctag/design-reviews/commits/426a9a8b3fc6314deb9f44a60ade76d2edaca6fd/ISSUE_TEMPLATE.md🔗

まず 2016年11月02日にテンプレートのファイルが作成されていました。

https://github.com/w3ctag/design-reviews/commit/9ed6f17be379a5d0d9397c5311ac9634fcab84d4🔗

コミットメッセージには「F2Fからの Issue template。共同で構築。」と記載があります。

Issue template from F2F. Collaboratively constructed.

この「F2F」について検索してみると、どうも W3C が開催している「Face to Face」 Meeting のことを指しているようです。

TAG Meeting 2016@Tokyo

2016年11月02日あたりに開催された TAG の Meeting を検索してみると、どんぴしゃで2016/10/31 - 2016/11/02 @東京開催のMTGがあることがわかりました。

https://www.w3.org/events/happenings/2016/technical-architecture-group-tag-meeting-2/🔗

Web サイトのリンクがあったので眺めてみる。どうも日経ビルでやっていたそうな。

https://github.com/w3ctag/meetings/tree/gh-pages/2016/11-tokyo🔗

議事録があるようですが、どれも W3C TAG のトップページに飛んでしまい参照できませんでした。最新の MTG の議事録の格納場所に移動されていないかみてみたものの、最近では直接 GitHub に保存しているのでダメそうです。

これ以上は追えないものの、ここを起源にテンプレートが生まれたことがわかりました。

greeting の変遷

https://github.com/w3ctag/design-reviews/commit/6bd78d4e674e5428c32f914bec64739164ba7a54🔗

テンプレートが作成されて以降、初めて挨拶部分が変更されたのがこのコミット。2017年07月にはたしかにロンドンで F2F MTG が開催されており、これに合わせて「Dear Sirs and Madam of TAG!」に変わっている。

テンプレートができた時から、初めて挨拶部分が変更されたときまでに、02-boston、04-tokyo の2回が開催されている。ボストンについてはアメリカなので変更の余地がありませんが、なぜ東京は変えなかったのか…（東京の時に Hello で作ったので、変えようと思わなかったのかも？）？

何はともあれ、2017年07月以降、その回の MTG の会期中に、次回の開催地の挨拶文に変わるという文化が始まったようです。

改めて「こんにちは TAG-さん!」を確認する

https://github.com/w3ctag/design-reviews/commit/d7015be036a57a19e9be170eeb914e425db9b65c🔗

この変更が入ったのは、2023年02月13日。確かに2023年04月には東京で F2F MTG が開催されているものの、それ以降も MTG は開催されており、一方で挨拶文は変わっていない。

よくよくみてみると、必ずしも毎回挨拶文が変わっているわけでもなく、厳格な運用（挨拶文の変更に厳格な運用も何もないが…）はされていないようでした。

おわりに

あまり重要ではない情報の調査に時間を使ってしまったような気がしましたが、調査の過程で W3C TAG に少し詳しくなれたのでよかったです。

「こんにちは TAG-さん!」とは何か

公開日: 2024/5/4

GraphQLの「Serving over HTTP」とは何か

2024/5/3

に公開

サマリ

モダンな Web アプリケーションフレームワークは、HTTPを用いてやり取りを行い、ミドルウェアを利用して認証やリクエストの検証、変換を行うパイプライン型のアーキテクチャを採用している
GraphQL においても、事前に認証・検証が行われた上でリクエストを処理するのがベストプラクティス
そのために、GraphQL のリクエストを REST のような形式でマッピングして処理する

Serving over HTTP

https://graphql.org/learn/serving-over-http🔗

GraphQL サーバは GET と POST の 2 種類の HTTP リクエストをハンドリングできるようにします。

マッピングされるパラメータは次のとおりです。

パラメータ	意味	必須
query	クエリそのもの	必須
variables	クエリの変数	任意
operationName	クエリの名前。複数のオペレーションを同時に実行する場合には必須	任意

GET

GET リクエストでは、GraphQL Query が query というクエリパラメータにマッピングされます。

query HeroQuery($id: ID!) {
  hero(id: $id) {
    name
  }
}

このクエリは、次のようにエンコードされます。

http://myapi.com/graphql?query=query($id: ID!){hero($id: ID!){name}}&operationName=HeroQuery&variables={"id":"avagfads732"}

POST

POST リクエストでは、application/json でリクエストを送信する。次の形式の JSON をボディとして送信されます。

{
  "query": "...",
  "variables": "updateHeroName",
  "operationName": { "id": "avagfads732", "name": "Andrew" }
}

レスポンス

レスポンスは JSON 形式で返される。GraphQL の仕様に則り、dataフィールドかerrorsフィールドが含まれます。

{
  "data": {
    "hero": {
      "name": "Andrew"
    }
  }
}

{
  "errors": [
    {
      "message": "Cannot query field 'hero' on type 'Query'",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ]
    }
  ]
}

[Draft] Transport Specification / GraphQL over HTTP

ここまでの内容が GraphQL 公式で公開されている内容で、ここから先はまだドラフト段階です。

仕様の定義場所

https://graphql.github.io/graphql-over-http/draft/🔗

概要

GraphQL over HTTP は Serving over HTTP の仕様を拡張したもの。
HTTP サーバは 1 つ以上の URL を介して、GraphQL スキーマへのリクエストを受け付ける必要がある。
サーバおよびクライアントは、少なくとも JSON の形式でリクエストをサポートする必要がある。
レスポンスにおける Media Type は application/graphql-response+json が推奨。
サーバは POST リクエストに必ず対応する必要があり、そのほかの GET のようなメソッドも対応する可能性がある。
サーバはリクエストの処理の成功時にはその結果を、失敗時にはエラーを返す必要がある。

GraphQLの「Serving over HTTP」とは何か

公開日: 2024/5/3

skim で移動/コマンド履歴検索をインタラクティブに行う

2024/5/2

に公開

モチベーション

新しく M3 Macbook Air を購入したので、これを機に色々とツールを乗り換えています。

Fuzzy Finder にはこれまで peco を使っていたのですが、全部 Rust 製に統一したいという思いがあり、skim に乗り換えました。

乗り換えたはいいのですが、キーバインドやコマンドの設定を怠っており活用できていなかったので、調べて設定してみた、というのがこの記事の内容です。

zoxide の絞り込みに skim を使う

https://github.com/ajeetdsouza/zoxide🔗

zoxide には標準で zi というエイリアスが設定されており、これを使うことでインタラクティブにディレクトリを選択できます。しかし内部的には fzf が使われており、そのままだと fzf もインストールしなければなりません。

これを skim で使うための設定が以下の Issue で提案されていました。

https://github.com/ajeetdsouza/zoxide/issues/228🔗

function __zoxide_zi() {
    \builtin local result
    result="$( \
        zoxide query -ls -- "$@" \
        | sk \
            --delimiter='[^\t\n ][\t\n ]+' \
            -n2.. \
            --no-sort \
            --keep-right \
            --height='40%' \
            --layout='reverse' \
            --exit-0 \
            --select-1 \
            --bind='ctrl-z:ignore' \
            --preview='\command -p ls -F --color=always {2..}' \
        ;
    )" \
        && __zoxide_cd "${result:7}"
}
zle -N __zoxide_zi
setopt noflowcontrol
bindkey '^z' __zoxide_zi

通常のシェルインテグレーションと同様に、__zoxide_zi 関数を定義し、zoxide query でディレクトリを取得し、sk で選択するようにしています。

https://github.com/ajeetdsouza/zoxide/blob/main/templates/zsh.txt#L69-L73🔗

履歴検索を skim で行う

最適かは分かりませんが、履歴検索を skim で行う設定を以下のようにしました。

function hist() {
    BUFFER=$(history -n -r 1 | sk --query "$LBUFFER" --reverse)
    CURSOR=$#BUFFER
    zle reset-prompt
}
zle -N hist
bindkey '^r' hist

zle、bindkey is 何？

Zsh Line Editor の略で、Zsh のコマンドライン編集機能を提供します。ターミナル上の文字列やカーソル位置をシェルスクリプト上で操作するための機能のようです。

今回出てくる -N オプションは、新しく関数をバインドするためのオプションです。

-N new-keymap [ old-keymap ] Create a new keymap, named new-keymap. If a keymap already has that name, it is deleted. If an old-keymap name is given, the new keymap is initialized to be a duplicate of it, otherwise the new keymap will be empty.

bindkey は、キーバインドを設定するためのコマンドです。指定したキーに対して、指定した関数をバインドします。

https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html🔗

参考

https://speakerdeck.com/naoya/sierunolu-li-toikunrimentarujian-suo-woshi-u🔗

https://k-koh.hatenablog.com/entry/2020/10/24/160323🔗

https://www.rasukarusan.com/entry/2020/04/19/193450🔗

skim で移動/コマンド履歴検索をインタラクティブに行う

公開日: 2024/5/2

Go におけるツールの依存関係を追跡できるようにする

2024/4/30

に公開

解決したい課題

gqlgen のように、ツールとしては確かにプロジェクトで使用しているけれども、アプリケーションのコードベースに出てこないパッケージを利用するケースがあります。

このようなツールは go mod tidy を実行した際に、import されていないため、module が消えてしまいます。

解決策

tools.go ファイルを作成し、そこで依存関係を追跡するツールをインポートすることで、Go におけるツールの依存関係を追跡できるようにします。具体的には以下のような tools.go を作成します。

//go:build tools
// +build tools

package tools

import (
    _ "github.com/99designs/gqlgen"
    _ "github.com/99designs/gqlgen/graphql/introspection"
)

このファイルで import が実行されているため、go mod tidy を実行してもツールの依存関係が消えることはありません。また //go:build tools を記載することで、このファイルは go build などのビルド時には無視されるようになります。

// +build tools は、このファイルが tools というビルドタグを持つことを示しています。

参考

https://go.dev/wiki/Modules#how-can-i-track-tool-dependencies-for-a-module🔗

Go におけるツールの依存関係を追跡できるようにする

公開日: 2024/4/30

GitHub Issue から Markdown ファイルを生成してブログ記事を公開する

2024/4/28

に公開

モチベーション

このブログは Astro を用いて実装されており、記事は Markdown ファイルとして管理されています。基本的に PC で作業しているのでこの形式でも問題はないのですが、たまにスマホから記事を書きたいと思うことがあります。

しかしながら記事は GitHub 上の Markdown ファイルとして管理されているため、スマホで書くにはやや面倒です。特に YAML フロントマターは PC 上では VSCode のスニペットにより簡単に挿入できるのですが、スマートフォンではそうもいきません。

GitHub Issue から Markdown ファイルを生成する

そこで、GitHub Issue から Markdown ファイルを生成する方法を考えました。

Markdown で管理することを前提として、スマホでも書きやすくするための選択肢としては次のようなものが考えられます。

GitHub Issue から Markdown ファイルを生成する
CodeSpaces を利用して、ブラウザ上で記事を編集する
記事作成用の Web アプリを作成する

今回はお手軽に実施したかったことと、CodeSpaces をスマホで触るのは体験としてやや無理がったので、GitHub Issue から Markdown ファイルを生成する方法を選択しました。

実装

全体の構成

GitHub Issue を作成する（Issue テンプレートとして、ブログのテンプレを用意しておく）
GitHub Actions でラベルが付与されたことをトリガーに GitHub Actions を実行する
1. ラベルを検知し、publish が付与されていれば後続の処理を実行する
2. Issue の内容から Markdown ファイルを生成する
3. Issue の内容を元に Markdown ファイルを生成し、新たにブランチを作成する
4. プルリクエストを作成する
5. 対象となった Issue にプルリクエストを紐付け、Issue を Close する
Cloudflare Pages　のプレビューが走るため、プレビューする
問題なければマージし、記事が公開される

GitHub Actions のワークフロー

GitHub Actions のワークフローは次のようになります。

name: publish content from GitHub Issue

on:
  issues:
    types: [labeled]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check issue labels
        if: contains(github.event.issue.labels.*.name, 'publish') != true
        run: exit 0
      - name: Define title
        id: define_title
        run: |
          title=$(echo "${{ github.event.issue.title }}" | sed -r 's/([a-z0-9])([A-Z])/\1-\2/g; s/ /-/g' | tr '[A-Z]' '[a-z]')
          echo "title=$title" >> $GITHUB_OUTPUT
      - name: Create Content File
        run: |
          echo -e "${{ github.event.issue.body }}" | sed -e "s/publishDate:/publishDate: $(TZ=-9 date -Iseconds)/" | sed -e "s/modDatetime:/modDatetime: $(TZ=-9 date -Iseconds)/" >> src/content/blog/${{ steps.define_title.outputs.title }}.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Commit Content File
        uses: EndBug/add-and-commit@v9
        with:
          new_branch: ${{ steps.define_title.outputs.title }}
      - name: Create PullRequest
        run: gh pr create --title "${{ github.event.issue.title }}" --body "#${{ github.event.issue.number}}" --base main --head ${{ steps.define_title.outputs.title }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Close Issue
        run: gh issue close ${{ github.event.issue.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Issue テンプレート

Issue を起点に作成するので、テンプレートも用意しておきます。

---
name: blog
about: create blog draft
title: ""
labels: ""
assignees: ""
---

## <!-- Issueタイトルはslugとして使用。時刻は埋めなくて良い -->

author: ikuma-t
publishDate:
modDatetime:
title:
featured: false
draft: false
tags:

- description:

---

##

Issue テンプレート自体の YAML フロントマターと衝突するため、やむを得ず一行コメントを挟んでいます。

ショートカットの追加

MacroDroid を使って、メニュー部分に「ブログを追加」ボタンを設置します。

Issue Template はクエリパラメータで設定できるので、その URL を登録しておきます。

GitHub Mobile で Issue 作成画面が開く

GitHub Mobile がインストール済みであれば、ブラウザではなくこちらで Issue を作成することができます。

Web 版よりも Markdown エディタが使いやすく便利です。

おわりに

GitHub Issue から Markdown ファイルを生成する方法を紹介しました。

画像の挿入には対応していないものの、比較的お気軽に記事を投稿できるようになり満足です。

GitHub Issue から Markdown ファイルを生成してブログ記事を公開する

公開日: 2024/4/28

このブログのパッケージマネージャを pnpm に変更した

2024/4/27

に公開

pnpm へ移行

もともとこのブログのリポジトリでは npm を使っていましたが、他の箇所では pnpm や bun を使っていることもあり、速度に不満があったため pnpm に移行しました。

移行手順

pnpm のインストール

npm install -g pnpm

既存の node_modules の削除

rm -rf node_modules

package-lock.json の削除

rm package-lock.json

package のインストール

pnpm install

補足： pnpm コマンドのみを許可する

package.json に以下の設定を追加することで、npm や yarn コマンドを使わないようにできます。

{
  "scripts": {
    "preinstall": "npx only-allow pnpm"
  }
}

なお only-allow🔗 は特定のパッケージマネージャのみを許可するパッケージです。

実際のところ、コマンド実行時は azu/ni.zsh: Alternative `ni` written in zsh: npm/yarn/pnpm/bun with the same command🔗 を使用しているので間違えることもないですが…。

このブログのパッケージマネージャを pnpm に変更した

公開日: 2024/4/27

VSCode Conference Japan 2024 で登壇しました！

2024/4/22

に公開

VSCode Conference Japan 2024 で登壇しました！

先日 4/20 に開催された VSCode Conference Japan 2024🔗 に登壇してきました！

VSCode Conference Japan のアーカイブ動画を拝見したことがあったのですが、参加するのははじめてでした。

自分の登壇内容

登壇資料・登壇動画

動画のアーカイブもあります。

モチベーション

RubyMine入門🔗 や Code Tour を使ってじっくり確実にコードを読む🔗、Railsアプリをコスパよく読むための環境整備🔗などなど、エディタ関連のアウトプットはあれど、カンファレンスには登壇したことないなあと思っていたので、今回の機会に登壇してみようと思いました。

プロポーザルは結構難産なことが多いのですが、ツール系は自分の趣味分野ということもあり、割とあっさりとテーマを決めることができました。

話せることが結構あるからあっさりテーマが決まったわけですが、登壇時間 15 分に対して、スライド 59 枚は多かったなあと反省しています。

発表の構成

そのまま並べても資料としては成立するだけのボリュームだったのですが、そうすると Tips 集になってしまって話を聞かなくてもいいかなと思いそう…と感じ、冒頭に「なぜ見た目から始めるのか」という Why からはいる形式に。

内容は普段業務でもやっている小さな改善系において考えていることの流用ですが、この進め方にしてみたところ扱う Tips の取捨選択がうまくできてよかったです。

感想

懇親会や X でも「参考になった」と言っていただけてとても嬉しかったです！

これまで自分の手元に溜め込んでいた「すぐアウトプットできるけど、1つ1つは記事にするほどでもない」ネタたちを一気に放出できてスッキリしました！

Biomeに寄付をすることにした

https://twitter.com/unvalley_/status/1781603651288809515🔗

同じく登壇されていた unvalley🔗 さんの登壇内容がとても印象的でした。

資料内で引用されていた資料も併せて貼っておきます。

https://erika.florist/articles/dontunderestimateeditorintegration/🔗

Biome 自体は新規で小さなツールを書く際に利用していたのですが、これを機にこのサイトでも Biome を利用するようにし、また Open Collective 経由で Biome への寄付を始めました。

https://opencollective.com/biome🔗

とりあえず $5 ずつ月額寄付をしていますが、これからも継続していきたいと思います（給料上がったらもう少し増やす）。

おわりに

最近ソフトウェアアーキテクチャの基礎を読んでから、技術に触れる時に Technology Radar の 4 象限を意識するようになりました。前々から薄々気がついていたのですが、自分はかなりツールに傾倒する傾向があり、時間の使い方的にどうなんだと思っています。趣味という点ではいいんですけどね。

なので今回ツール系のネタを放出できたのを一つの区切りにして、今後、最低でも半年はツール系のネタは封印してやっていこうと思っています。

区切りをつけようと思えたのは、年に一度の VSCode のお祭りで登壇できたから & 楽しかったからこそです。運営の皆様、ありがとうございました！

VSCode Conference Japan 2024 で登壇しました！

公開日: 2024/4/22

現在のディレクトリから新しいリポジトリを作成する

2024/3/11

に公開

何度やっても忘れるのでメモ。

private repository

gh repo create --private  $(basename $(pwd)) --push -s .

public repository

gh repo create --public $(basename $(pwd)) --push -s .

学習用のリポジトリを作成するときに便利。

現在のディレクトリから新しいリポジトリを作成する

公開日: 2024/3/11

ミスドのネット予約を使うと、チョコファッションのチョコを全体にかけられる

2024/3/10

に公開

この前初めてミスタードーナツを予約してみた際、「事前予約専用ドーナツ」なるものがあることを知りました。

https://www.misterdonut.jp/m_menu/new/240207_net_order/🔗

自分はミスドで何かを買う時、オールドファッション系のドーナツを頼むことが多いです（お腹に溜まるから）。当然チョコファッションも購入するのですが、景気とともにチョコの量がどんどん減ってきている気がしており、毎回ちょっぴりしょぼんとしていました。

https://www.misterdonut.jp/m_menu/donut/net_order24_01.html🔗

今回見つけた予約専用の「たっぷりチョコファッション」は、表面前面にチョコがかかっているというもの。注文の手間はかかりますが、通常のチョコファッションに 10円上乗せするだけで、チョコを3倍楽しめます。

特にオチはないです。

ミスドのネット予約を使うと、チョコファッションのチョコを全体にかけられる

公開日: 2024/3/10

Code Tour を使ってじっくり確実にコードを読む

2024/3/10

に公開

Code Tour を使ってじっくり確実にコードを読む

日々のタスクに忙殺されていると、ついつい既存コードを流し読みして、ざっと動くコードを書いてしまいたくなります。一発でうまく動けば短期的にはいいのですが、長期的にはコードの理解が追いつかなったり、一発でうまく動かなかった場合にかえって時間がかかってしまいます。

VSCode の拡張機能である Code Tour を使うと、コード上にメモを残しながら読み進めることができるので、既存のコードを読む際に便利です。

Code Tour とは

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

VSCode の拡張機能で、コード上にメモを残しつつ、そのメモをたどることができるツールです。

使い方

ツアーを始める

コマンドパレットから「Code Tour: Record Tour」を選択すると、ツアーの記録モードになります。

ツアーの名前
どのソースに紐づけるか（紐付けなし、ブランチ、タグ）

を選択すると、リポジトリ直下に .tours/${指定したツアー名}.tour というファイルが作成され、ツアーの記録が開始されます。

メモを残す

ツアー記録モードだと、エディタの行番号横に「+」ボタンが表示されます。単一行または複数行を指定することで、その行にメモを残すことができます。メモには、Markdown が使えるので、コードの説明や、参考リンクなどを記述することができます。

シンタックスハイライトも適用されるので、「自分の見慣れない文法だったので、小さいサンプルとともにメモしておきたい」「ライブラリの実装を読んだので、関連部分にメモしておきたい」などの場合にも便利です。

ツアーの記録を終了する

コマンドパレットから「Code Tour: End Tour」を選択すると、ツアーの記録が終了します。

ツアーを再生する

コマンドパレットから「Code Tour: Start Tour」を選択すると、ツアーの再生モードになります。

各ツアーのメモにはページ送りボタンがあるので、これを利用して前後のツアーに移動することができます。

なお画像中の Insert: Code はコードブロックがある場合に表示されるもので、これを押すと、そのコードブロックがエディタに挿入されます。

ユースケース

開発中のサービスの特定機能の概観を理解したい

サービスの機能の振る舞いは知っているけど、実際のコードとしてはどういう構成になっているのか実は把握できていない、というケースで Code Tour を利用しています。

読み方は掲載した図の通りで、

エントリポイント（UI、ジョブ、CLI…）にメモする
機能のアウトプットを行って箇所（レスポンスを出力しているところ、帳票やログ出力）にメモする
どういうデータ構造で保存しているかメモする
外界からの入力をどう受け取っているのかメモする
ビジネスロジックをどう実装しているかメモする

といった感じです。

ビジネスロジックの部分は複雑になりがちなので、設計によってはいくつかのファイルに散らばることもありますが、これによりそれぞれのファイルにメモを取るとどうしてもメモが多くなってきたり、Tour も行ったりきたりになってしまいます。

そのためコアのファイル以外は精読せずに、ざっくりとインターフェースからこんなことをやってくれそう、という内容をコアファイルのメモとして取るようにしています。

反対にコアとなるファイルはちょっとした文法でもわからないところがあると、全体像がボヤけるので全力で調べてメモを残しています。

特定のライブラリに依存した機能を理解したい

[!NOTE] ここでいうライブラリとは管理機能やドキュメント生成ライブラリなど、土台となるフレームワーク（React、Next.js、Rails、Spring Boot など）の上に乗り、特定の機能群を実現するライブラリを意図しています。

例えば管理機能を作る場合に React Admin を使っていたりすると、React は知っていても、React Admin がいい感じに隠蔽しているので、どうやって書けば良いかスッとは出てこない、というケースがあります。その際には Code Tour を使って公式ドキュメントと実際のコードを読んでいます。

管理機能系であれば、通常のコードと別ディレクトリ（例： app/admin）に分かれていることが多いので、ツアーを始める際にはディレクトリをエントリポイントにします。

ディレクトリを指定して「Add Code Tour Step」を選択することで、ディレクトリに対してメモを取ることができるので、最初に公式ドキュメントや全体像をメモするようにしています。

ディレクトリのツアーに対しても、仮装のファイルが開き、通常のソースファイルと同様にメモを確認することができます。

ディレクトリ内に置かれているファイル数にもよりますが、なんとなく頭の中に知り合いを増やしてからドキュメントを読んだほうが個人的には馴染みが良いです。

そのためざっとすべてのファイルに目を通しつつ、よくわからないDSL的なものが出てくれば「なんだこれ？」とだけメモし、あとはドキュメントに書いてある内容や実際に動かした挙動で随時編集しています。

おわりに

以前はコードを読む際にソースコードのURLとメモをマークダウンファイルに残していましたが、Code Tour を使うようになってからはソースコードとメモが一体化しているので、読み進める際にスムーズになりました。

私は .tours ディレクトリをグローバルに ignore しているのでチームには共有していませんが、Gist経由で記録したツアーを共有することもできるので、チームでのコードリーディングにも使えるでしょう。

Code Tour で素敵なコードリーディングライフを！

Code Tour を使ってじっくり確実にコードを読む

公開日: 2024/3/10