はじめまして。今年の 7 月から HRBrain でフロントエンドエンジニアをやっている山本です。
普段趣味で開発者体験を高めるツールを OSS として作っています。
今回社内の開発者体験を高めるべく、ドキュメントとして残っていた社内のコード規約を ESLint のプラグインとして作成しました。
そこで、公開した動機、過程を紹介します。
動機
いくつかありますが、
- ドキュメントの情報は廃れていく
- ドキュメントは無視できる
ということが大きかったです。
ドキュメントの情報は廃れていく
ドキュメントを継続して整備・更新する人がいれば話は別ですが、基本的に、ドキュメントに書いてある情報は時間とともに現在のものと乖離していく、と僕は考えています。
情報の乖離に気がついた人が更新するといったスタンスであっても、気がつけられるほどの知識をその人が持っているとも限りません。
ドキュメントの内容が違ってくると、何が正しいのか、結局現状を把握するために人に教えてもらうことになります。
情報に不足がないか、複数人に聞いて回ることもあると思います。
そして、聞いた情報をドキュメントに残すかどうかは人によります。ガチャです。
ドキュメントに強制力はない
規約をドキュメントに書いても、そのドキュメントに強制力はありません。
誰かがドキュメントに書いてある規約を引っ張ってきて適宜忠告をすることになるでしょう。
つまり、誰かが忠告しない限り、ドキュメントの内容は無視できることになります。
また、忠告したとしても、ドキュメントの規約を都度引っ張ってくるのは時間がもったいないです。
静的解析に任せたい
コード規約は文章化しても廃れる、強制力はないため、何かツールを使って縛れないか考えました。
そこで、普段趣味で開発していて知見がある ESLint のプラグインだったら、これらをうまくカバーできるのではないかと考えました。
また、使い方という形で規約の内容や意図を伝えられることができ、廃れる、強制力のなさをカバーすることが可能です。
過程
開発に使うツール
主に以下のツールです
- commitizen/cz-cli
- commit message の統一によって、CHANGELOG の生成に統一性をもたせるため
- commit 時の typo を防ぐため
- typescript-eslint/experimental-utils
- TypeScript を使って ESLint のプラグインを作るため
- algolia/shipjs
- npm publish のフローの簡略化のため
ルールの洗い出し
明文化されていたルールは主に 2 つ
- import には name space import を使用する
import * as NameSpace from 'module'みたいなやつ- import するときに変数の衝突を避けられる
- tree shaking はできるので問題ない
- 内部で children を使わない Function Component には、
FunctionComponent<Props>やFC<T>を使う代わりに、返り値にReact.ReactElementを使う- children が optional になるとはいえ、children がいずれ来るかもしれないという宣言にも見える
- 使う使わないは好みの問題ではあるので、どうするのかは統一したほうが良さそう
あと 1 つに暗黙知として、
- named import が 2 つ以上は許容しない
import { A, B } from 'module'みたいなやつ- 2 つ以上なら name space import を使用する
- 1 つなら許可
LICENSE をどうするのか考える
Apache License 2.0 で作りました。
これに関しては、別の記事で紹介しようと思います。
ルールを作成
typescript-eslint チームが作っている experimental-utils を使ってルールを作っていきます。
これに関しても、別の記事で紹介しようと思います。
plugin として npm publish して公開
作り終わったら、shipjs を使用して npm publish していきます。
これに関しても、別の記事で紹介しようと思います。
完成
HRBrain の規約が詰まったプラグインが完成しました。
hrbrain/eslint-plugin: ESLint plugin for HRBrain
現在ルールは 3 つですが、今後も追加していく予定です。
最後に
ということで、
文章で規約を書いても、廃れる、強制力はないということで、ESLint のプラグインに規約を落とし込みました。
話が少し変わりますが、社内で誰かが言っていた「そういうことが可能ってことは、いくら仕組みで固めても人は（悪気がなくても）やっちゃう」って言葉が個人的に刺さっています。
今回だと、PR のレビューなどで指摘するという仕組みを導入したところで、指摘漏れといったことでかいくぐることは出来てしまいます。
静的解析でコードエラーとして規約違反を警告することで、もう一歩踏み込んだ規約の厳格化、指摘の手間をへらすことが出来ます。
次回はLICENSEをどう考えたのかについて紹介します。
