コーダーのための社内向けコーディングガイドラインを作成してから一年。いろいろ学びがあり、今のAI時代に必要なのではと感じたので個人の整理も兼ねてまとめています。
結論として
コーディングガイドラインの作成経験は「人にしか出来ない仕事」を教えてくれました
コーディングルールを作ることになったきっかけ
背景には、日々の開発で感じていた以下の課題がありました。
- 作業者ごとに書き方や考え方が異なり、修正や引き継ぎのコストが高い
- レビュー時に「何を基準に見るか」が人によって違う
- 自分たちの考えを整理し、新人教育にも活かしたい
その場その場での判断に頼るのではなく、
共通の認識を言語化しておく必要性を感じたのがスタートでした。
目指した姿
ルール作成にあたって、最初に意識したのは「何を目指すのか」でした。
- ガイドラインを軸にシニアからジュニアへの一方向的な教育的なレビューだけではなく、ジュニア同士、ジュニアからシニアへの多方面のコミュニケーションを生むこと
- 「ルール」ではなく「ガイドライン」。使いたい人が使えるもの
- 縛りを増やさず、一定基準の品質を担保すること
過剰なルールは思考停止を招き、生産性を下げてしまいます。
縛らないけれど、迷った時の拠り所になる。誰もが議論に参加できる。、そんな位置づけを目指して制度設計を考えていました。
作成したもの
具体的には、以下のようなものを整備しました。
- HTML / JavaScript / CSS / デザイン思想のガイドライン策定
- FLOCSS をベースにしたテンプレートの作成
- VS Code の拡張機能「HTML-validate」の共通設定ファイル
目的はあくまでルールではなくガイドラインなので、単なる「書き方のルール」だけでなく、 なぜそう考えるのかという背景や思想もなるべく言語化するようにしました。
また各所で守らなければいけないものではないという事を強調しています。
やってみて得られた恩恵
実際に取り組んでみて、いくつか大きなメリットを感じました。
①縛りにならない規則を考える経験が得られた
ルールを増やしすぎると、途端に「守ること」が目的になってしまいます。そうならないように「ゆとり」を含めた設計を行なった経験は、ガイドライン作成だけでなく要件定義や設計などの他業務にも良い影響を与えてくれました。
知識のない方にも伝わるように説明を考えたり、不要な制限を無くして使いやすい仕組みになるよう抽象化した経験が自分にとって思わぬ副産物となりました。
②自分自身の作業効率が上がった
- class 名や命名で迷うことが減った
- 他者のレビュー時に意図が読み取りやすくなった
- 案件の引き継ぎ時にも理解が早い
ガイドラインは、まず自分自身を助けてくれる存在でした。
③フロントエンドの歴史・思想を体系的に学べた
BEM や Atomic Design などの考え方を整理して文章化する過程で、
- なぜそういう設計が生まれたのか
- それが Tailwind CSS や CSS in JS にどう繋がっているのか
といった流れを理解でき、フロントエンド設計への解像度が上がりました。
うまくいかなかったこと
もちろん、すべてがうまくいったわけではありません。
①多方向のコミュニケーションは簡単ではなかった
仕組みで品質や効率は変えられても、
人の意識や行動を変えるのは難しいと感じました。
- 誰かに意見することの得意・不得意の差
- そもそも「この規模のコーディングにレビューは必要か？」という問題
- 同じ立場や下の立場から意見を受ける事に対する嫌悪感
ガイドライン以前に、メンバーや案件の性質を考える必要がありました。
また自分自身のレビューの精度が上がった事により、良くも悪くもメンバーの心理的安全性が高まり、レビューの需要が減ったという事実はあります。
②拡張機能があまり使われなかった
HTML-validateを導入しましたが、コード品質よりも速度を重視する案件が多く、出番が少なかったこと。
評価が細かく、開発中に邪魔だった事もありオフにしている事が増えました。
結果的に余裕のある際に自己品質管理の一環として確認するものという立ち位置になり、余裕のない我々には縁のないものになっていきました。
これからの AI 時代に向けて
AI がコードを書く時代になっても、
コーディングルールの必要性自体は変わらないと感じています。
- AI に伝えるか、人に伝えるかの違いなだけで「共有する力」は今後も効率化のために必要
- どう伝えれば縛りにならず、生産性を下げないかという感情に即した配慮は人間の仕事
- 人や AI が作った成果物を正しく評価し、ブラックボックス化しないためにも「良いコードとは何か」を考えることが不可欠
コーディングガイドラインの作成を経ることで、
未来の自分やチーム、そして AI との共通言語になるものだと思います。
おわりに
完璧なルールを作ることよりも、
「考え続けるための土台」を作ることに価値がありました。
これから何かしらのガイドラインを作ろうとしている方のヒントや原動力になれば嬉しいです。