こちらの記事はhacomono Advent Calendar 2023の10日目の記事です。
はじめに
こんにちは。今年2023年の10月に入社した@gaaamiiです。UXチームというチームに配属となり、主にウェブフロントエンドの開発やAPIの改修に関わっています。アドベントカレンダーに乗じて、入社して初のTechブログ記事を投稿させていただきます！
この記事では、私がいま関わっている大きめのリポジトリのフロントエンド部分において、ドキュメントを少しずつ改善していく話を書きます。
背景
今回改善しようとしたのは、hacomonoのメンバーサイトと呼ばれるウェブアプリケーションについてのドキュメントです。メンバーサイトはメインサービスのエンドユーザー向けの画面であり、開発にも多くのエンジニアが関わっています。メインサービスということもあり大きく昔から動いているものなので、現在もVue 2で動いており、コンポーネントの書き方も複数混在していました。
Vueは2と3で書き方が変わっている部分がいくつかあります。たとえばメンバーサイトでいうと、Vue 2時代にTypeScriptの恩恵を受けるためにVue Class Componentというライブラリを使ってクラスベースの書き方をしていましたが、このライブラリの利用はVue 3では推奨されておらず、ライブラリ自体のメンテナンスがされていない状況です。このような状況でVue 3への移行を意識すると、少なくとも新規の実装においてはこうした書き方はされないようにしたいです。
こういった注意が必要なコーディングがところどころにあるので、開発者で認識を合わせ、ドキュメントでも推奨の書き方と非推奨の書き方を明示しておきたいと考えました。
更新しやすく参照しやすいドキュメントにするため、GitHubリポジトリに移動
メンバーサイトのドキュメントはNotionのページで管理されていましたが、ところどころ古い内容が残っており、ドキュメントの更新がしづらい状況になっているのではと感じました。また、コーディング時はいつもこのNotionページを開いているわけではないので、必要になるたびにNotionのページを検索する必要があり、参照もややしづらいと感じていました。
そこで、GitHubリポジトリに同様の内容を書いたMarkdownファイルを置き、Notionページのほうは廃止することにしました（こういった相談をするため、隔週でフロントエンド実装に関わる人が参加する相談会を設けさせていただいています。これについても後述します）。
現在は、開発ドキュメントは docs/ ディレクトリにまとめ、プロジェクト直下のREADME.mdから各ドキュメントへのリンクが貼られています。個人的にはREADME.mdを開けば探しているものが見つかるというのが嬉しいところです。
ドキュメントを管理する場所としてどこが良いかは正解がないかとは思いますが、今回のようにコーディングスタイルなどを書いた開発者向けの情報は、GitHubリポジトリでの管理にすることで以下のメリットがあると考えています。
- ソースコードと近い場所にドキュメントが置けるため、開発時に参照がしやすい
- コミットログが残るので歴史を追いやすい
- Pull Requestの仕組みがあるため、ドキュメントの修正を提案しやすい
一方、開発者以外も閲覧できる・レビューのプロセスを経ずにすぐ更新ができるなど、NotionのようなWikiにもメリットがあるため、ものや状況によってどちらが適しているかは変わるかと思います。
推奨と非推奨を区別する
このドキュメントの「アーキテクチャ・記述方針」の中身を読むと、非推奨の書き方と今後推奨される書き方が区別して記載されています。たとえば以下のような内容です。
- BaseMixin になんでもアクセサを突っ込んでしまったが故に、全てのコンポーネントが BaseMixin に依存している現状があるが、これを非推奨とする
- Mixin はそもそも Vue2 の中期までは推奨されていたが、現在は Composition API の登場とともに非推奨となっている
- mixin は将来的には廃止予定
特に新たに開発に入る開発者にとって、これは重要な情報です。Vueに詳しい開発者がこのドキュメントを読めばmixinを剥がすリファクタリングをしてもいいのだなと考えるでしょうし、Vueに疎い開発者であっても、新たに書く際はmixinの利用を避けるでしょう。
暗黙のルールを見つけたらドキュメントを更新してPull Requestを投げる
ドキュメントをGitHubリポジトリに移動しただけでは、少し参照しやすくなった程度であまり効果はありません。今後はコードレビューのタイミングでドキュメントを少しずつ更新していきたいと考えています。
コードレビューでコーディングスタイルについて指摘があるということは、開発者間でコードの書き方について認識が合っていないということです。ドキュメントに書いておくと次からそのようなレビューコストが減ります。
たとえば、以下は、私がCSSのclass名について指摘をいただいて、ドキュメント更新をするまでの実際の流れです。
こういったことを繰り返していけば、ドキュメントが頻繁に更新され、その時々の最新のものになるのでは、と期待しています。
フロントエンド相談会
些細なことであればPull Requestベースのコミュニケーションで問題ないかと思いますが、あるとより嬉しいのが開発者同士で相談ができる場です。コーディングスタイルや実装手段は開発者ごとにこだわりがある部分もあります。人によって実装方法がぶれやすいところはある程度相談をした上でドキュメントに反映しておきたいです。
そこで、隔週でフロントエンド相談会という会を設けるようにしました。ここで、hacomonoのフロントエンドに関わる相談などをしています。ドキュメントをGitHubリポジトリで管理する話などもこの会で相談をして進めました。
今後の課題
今後もドキュメントを改善していきたい一方、不要なドキュメントは消していきたいとも考えています。特にコーディングスタイルのようなものはLintを設定すれば不要になるものが多いため、ドキュメントはそれができるまでの一時的な対応として、Lintに寄せていくようにしたいです。
まとめ
フロントエンドは周辺ツールの変化などもあり、推奨されるコーディング方法も変わることがありますが、コードベースが大きいと全てを最新の書き方にリファクタリングしながら進むのは難しいです。せめてドキュメントによって、新たに書く部分についてはどう書くのが良いのか、というのが明示された状態にしていければと思っています。
株式会社hacomonoでは一緒に働く仲間を募集しています！
採用情報や採用ウィッシュリストも是非ご覧ください！
