イネーブリングチームの東です。
DDD好きですか？僕はそこそこです。
DDD、やってみると簡単ではないんですよね。
ユビキタス言語導入の背景にある、「同じ言葉で話したい」というシンプルな願いであっても、3人ほど集まればもう困難になります。
頭ではわかっていても、実践できない。僕もそんな一人です。
この課題に対し、エンジニアにとって身近なCIやエディタに実践するための仕組みを導入する形でアプローチしようと考え、@tokiumjp/dictを作ることにしました。
ユビキタス言語を書く
構想
ユビキタス言語をコード上に記述して運用していくうえで、本当にコードにユビキタス言語が書かれているかどうかをチェックできるような構造を考える必要がありました。
第一に、ドキュメントの構造設計です。ユビキタス言語の名前と説明が最低限必要です。
また、抽出しやすいような構造にする必要があります。
コメントを扱うだけなら、ただの文字列処理です。コメントにユビキタス言語の名前と、その説明を書いてもらうことにします。
幸い、弊社が採用しているRubyはコメント処理が楽でした。
第二に、コード内に書かれたドキュメントの抽出と検知です。ファイル内のクラスやメソッドに書かれたコメントから、前述のユビキタス言語が書かれていなければエラーとして検知します。
これは、CI等に組み込むことを前提として考えると、CLIツールとして開発する必要があります。
ドメインとは無関係なファイルを含む全ファイルを対象にすることは難しいので、特定のディレクトリ配下のクラスに対してのみ適用できる必要があります。
実現
ファイル内に特定の形式のコメントを記載できるようにする
名前と説明文が必要なので、それぞれ@dict-name,@dict-descで記述することにします。
ユビキタス言語が指すクラスに対して、上記のフォーマットで記述します。
# app/models/user.rb こっちはユビキタス言語を適切に書いた例
# @dict-name ユーザー
# @dict-desc ユーザーはシステムの利用者です。メールアドレスとパスワードでログインできます。
class User
end
# app/models/company.rb こっちはユビキタス言語を書かなかった例
class Company
end
クラスに特定の形式のコメントが書かれているかどうかをチェックする
dict checkコマンドで@dict-name, @dict-descが書かれているかどうかをチェックします。
クラスとメソッドに対するチェックができるように作っていますが、今回はクラスのみチェックします。
dict check --input app/models --type class
コメントが書かれていないクラスが検出できました。
app/models/company.rb [class] Company
exit 1
CI(Github Actions)への組み込み
CLIツールで検出できるようになったので、みんなの業務に組み込みましょう。
PRを出したときの差分にだけ適用しておくことで、漸進的にユビキタス言語が書かれる状態を目指します。
みんなに一言伝えておくことも重要です。
# コード上にユビキタス言語辞書(@dict-name, @dict-desc)が書かれているかチェックする
name: Dictionary Check
on: pull_request
jobs:
dict-check:
runs-on: ubuntu-latest
name: Dictionary Check
permissions:
packages: read
contents: read
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v3
with:
node-version: 16
- name: install dict
run:
npm install -g @tokium/dict
- uses: technote-space/get-diff-action@v6
with:
PATTERNS: |
app/models/**/*.rb
- name: dict diff class
run: |
dict check --input ${{ env.GIT_DIFF_FILTERED }} --type class
if: env.GIT_DIFF_FILTERED
結果
2ヶ月ほどで、100件のユビキタス言語が記載されました。CIの力は強いですね。
ユビキタス言語を使う
構想
前段までの取り組みで、ユビキタス言語が集まりました。これを活用し、辞書のように調査に使えるようにしたいと思います。
コードを読んでいる際に、外部のウェブサイトやツールに離脱することなく、自然な形で目に触れる情報にできると理想的です。
また、何の情報も持たない人はどんな概念が存在するかもわからないので一覧など網羅的に情報に触れられる場所も必要ですし、閲覧している情報の成否も確かめたり、修正しやすくなるような仕組みもほしいところです。
弊社の開発者の大半はVS Codeを使って開発しているので、VS Codeプラグインvscode-dictを作ることにしました。
実現
コメントホバーで、ユビキタス言語を表示できるように
コードを読むときは、コメントが頼りになりますよね。
コメント内に含まれるユビキタス言語の情報を表示してみます。
ユビキタス言語の詳細を見られるように
ホバー内の青いリンクをクリックして、詳細をみられるようにします。
サンプルなのでミニマムではありますが、説明文にもリンクがあって、言及されている場所に飛ぶことができます。
サイドバーではすべてのユビキタス言語が一覧できるようになっていて、気になったものはクリックすることで同じように詳細をみられます。
結果
100件ほどのユビキタス言語からなる辞書ができあがりました。
ユビキタス言語の調査も追加も修正も、コードコメントの変更で実現できます。
総論
プロダクトに関するあらゆるドキュメントや議論は、完全に整備されていなくてもユビキタス言語をベースに行われます。
新しくチームにジョインする人はみな経験もスキルもバラバラですが、既存プロダクトへの理解は等しくゼロに近い状態です。
この領域こそが現在最もイネーブリングの価値がある領域とさだめ、プロダクトに関する知識を獲得しやすくする必要がありました。
そのため、VS CodeやCI等、業務上触れる機会が多いツールに寄り添うかたちで展開し、自然に使ってもらえることを目指しました
これらが本当に役に立ったのかの計測はまだこれからですが、執筆時点で6人ほどがVS Code拡張をインストールして使ってくれているようです。
TOKIUMでは共に働く仲間を募集しています。
一緒に開発をハックしましょう。
Discussion