システム開発グループのガイドラインの見直しと活用のポイント
目次
こんにちは、まおです。
皆さんの会社にコーディングガイドラインはありますか？どのように活用していますか？今回はシステム開発グループ（以下、シス開）で以前実施したガイドライン見直しの話と、日々の開発に活かしている工夫を紹介します。
そもそもガイドラインとは？なんのためにあるの？
ガイドラインは特定の目的や行動を指し示した指針や基準のことです。コーディングに関することですと、インデントの数や変数の宣言方法、クラスの命名規則などコードの書き方を定めてます。シス開ではConfit、SMOOSYで細かい違いはありますが、基本的には共通のガイドラインを使用しています。
ガイドラインでコードの書き方を統一することによって、チーム全体が共通の基準を持つことができます。これにより、読みやすく理解しやすいコードとなり保守性が向上します。保守性が高いとコードの修正やバグ修正もしやすいので、結果的にサービス全体の品質向上に繋がります。
アトラスではコーディングのガイドライン以外にも、デザインやロゴの使用方法、文章の書き方のガイドラインも存在します。デザインや文章はユーザーやお客様に直接触れるものです。その質にブレがあるとイメージや信頼性に直結します。コーディングガイドラインと同様に、統一性のあるデザインや文章をつくりあげることで、品質およびブランディング向上が期待できます。
ガイドラインの作成と見直し
作成にあたって
ガイドラインをいちから作成する場合、無理のない範囲でルールを決めていくことをおすすめします。以前アクセシビリティガイドラインを作成したときも同様に、Web Content Accessibility Guidelinesの達成基準であるレベルA・AAを対象としました。ガイドラインで大事なことは作ることではなく、使い続けていくことだからです。
ガイドラインを公開している企業もあるので参考にしてみるのもポイントです。シス開のHTMLとCSSのガイドラインはGoogleスタイルガイドと、「HTML解体新書」を参考にしています。
また、品質向上のためにも、ガイドラインの内容は作り手が一方的に決めるのではなく、「この項目は何故こうなっているのか」という理由を入れたり、使用するメンバーにレビューしてもらうことも必要です。
見直しの流れ
ガイドライン作成後も定期的な見直しが必要です。シス開は2年前のNotion導入タイミング時にガイドラインを見直しています。
当時見直したガイドラインの一部は以下の通りです。
- HTML
- CSS
- TypeScript
- JavaScript
- Java
- アクセシビリティ
- Confit用のデザインガイドライン
見直しは私とkimuraの2名で実施しました。私はデザイナー、kimuraはエンジニアということで、それぞれ業務でよく使用するガイドラインを手分けして各自進めていきました。
以下に、見直しの流れを簡単に説明します。
- 既存ガイドラインの洗い出し
- 廃止するガイドラインの選定
- 各自ガイドラインの見直し（週1回Slackで簡単に1週間の進捗と翌週の予定を共有と、月末には30分ほど時間をとって進捗会を開催）
- メンバーへレビュー依頼
- 見直し後のガイドラインを正式に公開！
活用するガイドラインへ
せっかくガイドラインを見直すのであれば！ということで、しっかり活用していきたいと思い、こんな工夫をしています。
ガイドラインのチェックリスト版も作成してプルリク時のセルフチェック資料として組み込む
今回の見直しでガイドラインのチェックリスト版も作成しました。チェックリスト版はGitHubのプルリクエスト作成時のテンプレートに組み込んでおり、レビュイーが最後にセルフレビューできます。これによりレビュワー/レビュイー双方のレビュー負担を軽減することができます。
ガイドラインによってはESlintを導入してルール化
TypeScriptやJavaScriptはガイドラインではなく構文チェックツールEslintをプロジェクトに組み込みました。プロジェクトに記述ルールを設定することで、実装の時点でエラーや警告として自動検知されるので効率的です。見直し前はConfitやSMOOSYの各リポジトリでルールや使用Lintも異なっていたのでこれを機に統一できました。
導入についてはkimuraの「ESLintの共通ルール導入とその効果」に詳細が書いてあるのでこちらもご覧ください。
適宜みなおし・更新
シス開メンバーにも協力してもらい、ついに見直しできたガイドライン！しかし、もちろん作成時と同様、見直して終わりではありません。見直し後も適宜修正や補足を加えています。
実際に使用していくなかで疑問に思う箇所はメンバーからコメントをもらったり、ふと「この内容で本当に良いんだっけ？」という項目は再調査・再検討をしたりして、確認をしています。
適切なガイドラインを保つために、最新の情報収集も欠かせません。アクセシビリティに関しては昨年10月にWCAG2.2が勧告されたので、アクセシビリティガイドラインも既存内容に補足が必要そうです。
さいごに
以上、シス開のガイドライン活用方法でした。
ガイドラインはただ存在するだけでは意味がなく、使い続けていくことではじめて効果を発揮します。もしガイドラインが存在するだけの状態であったり、何年も内容を更新しておらずに古い情報や指針のままですと、開発プロセスや品質における問題が生じてしまうかもしれません。もしこの記事がガイドライン見直しのきっかけになれば大変うれしいです。
