ジュニア開発者がコード規約を初めて始めるとき
私が初めて会社に入ったときは、もどかしいことがたくさんありました。
特にコードを見ると、なぜこんなにif文とfor文がネストされているのか、なぜこんなにコードが乱雑なのか、なぜこんなに変数名が変なのか、などです。
会社に入って過ごしていると、もちろん人の能力が不足しているからという納得しやすい理由を挙げることができますが、実務経験が積もれば積もるほど臨機応変に対応しなければならないことや既存の設計と異なる方向の企画など、本人が開発していてもさまざまな理由でコードが乱雑になる場合が多いです。
そのようなことに助けを与えるのが、協業時のコード規約ですが、その理由は強力なルールを通じてコードの品質をかなり短期間で向上させることができるからです。（特にコードレビュー文化がある場合、肯定的に定着する可能性が非常に高いです。）
この文では短いですが経験を通してコード規約を導入する際にどのような点を考慮したのか、その中でジュニア開発者がどのようにしてコード規約を提案し、会社に適用したのかを書いてみようと思います。
コード規約はなぜ必要なのか？
実際、コード規約というものは2人以上で開発を行うとき意味があります。
1人開発の場合、本人がすべてのパートに責任を持ち開発を行うでしょう。また、本人の規則ですのでコード規約にこだわる必要はないと思います。
しかし、2人以上での開発を視野に入れている、またはすでに2人以上で開発している場合は、それぞれのコードスタイルが異なるため、プロジェクトに参加する人数が多くなればなるほど混乱する可能性があります。
コード規約は最も直接的にコードにルールを付与するものであるため、コードの品質を一定以上の水準に引き上げることができます。また、コード規約を熟知している人員が多くなればなるほど、コードがまるで1人が書いたかのように読めるため、コードの一貫性を維持し、誰もが予測可能なコードを書くことができるようになります。
ただし、コードにルールを課す行為であるため、プロジェクトメンバーの抵抗や、コード規約を作る理由についての説得が必要であり、この文ではそれについてどのようにアプローチしたのかについて書いてみようと思います。
コード規約を導入する際の障害
個人的に全員が大企業に勤めているわけでもなく、スタートアップ、中規模の企業に勤めていても、体系的なコード規約を通じて開発を行うことを見るのは容易ではないと思います。その理由については、いくつかの理由があるでしょう。
1. 初期スタートアップの場合、会社（代表）が望まない。
初期スタートアップ、つまりまだ収益を出していない会社の立場では、コード規約を作り維持することも費用の問題に直結すると認識する場合が多いです。
私はその部分に関して一部肯定しつつ、一部は否定する立場です。
実際にコード規約を記した文書があったとしても、言語のバージョンがアップグレードされたり、新しいツールを導入するなど、コード規約の管理が疎かになると、その存在意義が薄れることがあります。
初期スタートアップの場合、そういう文書を作るよりも一行のコードが、一つの機能がより重要だと考える場合が多く、私はコード規約の管理コストがかなり大きいと考えているため、ある程度その部分について制約が伴うと思います。
JSPを使用していた会社がSpringに変更する際にコード規約文書を再作成するコストを負担できるでしょうか？DB接続、コントローラの書き方、SSR方式からRestful APIへの変更など、確固たるコード規約文書が共にあったとすれば、変化に対するコストも大きくなることでしょう。
ただし、初期スタートアップも徐々に規模が大きくなり、開発する人数が増えるにつれて、コードには様々な人の直感が反映されたコードが書かれることになります。こうしたコードは、作成者以外にとっては保守が難しくなり、create, getなどの単純な命名であっても、意図や動作を推測しにくくなる場合があります。 （実際にcreateで始まったのに、あるメソッドはDB保存を、あるメソッドは一時的なエンティティを返す役割だけをするという場合もありました。）
これらが長く続くと、また管理する人が退職する場合には保守性が極めて難しくなることがあります。このような場合、初期スタートアップにおいても一部の必須項目についてコード規約を導入するのが良いと考えます。
2. コード規約は皆が納得しなければならない。
ジュニア開発者として痛切に感じたことの一つは、自分が特定の方式を良いと思っても、他の人がそれを気に入らなければ、それをコード規約にするのは難しいということです。
特にコード規約を夜を徹して作ったとしても、それを開発者が従わないなら、ただ自分の体力を消耗したに過ぎないのです。
したがって、コード規約は生まれたときから同僚開発者の協議が必要であり、コード規約の必要性自体を開発者に納得させる必要があります。
以下は、私がコード規約を作るために納得させた一連の過程を例に記述したものです。
以前、あるサービスを提供していたとき、サービス層でリポジトリ層にフィルタリングするコードを
適用せず、ラベル付けしたすべてのデータを消してしまうところでした。(もちろん、プロダクションではありませんでした。)
その後、リポジトリで全データを条件なしに修正または削除しないように有効性検査をしようと提案しましたが、このようなフィードバックを受けました。
- 初めて発生したケースを防ぐためにコード規約として導入するには、コードを作成するコストが増加しないでしょうか？
- 正しい指摘でした。すべてのデータ層に有効性の検査を入れると、開発時間だけでなくテストコードを作成する際にも時間がよりかかるでしょう。
- ビジネスロジックとは無関係なことがリポジトリ層の目的だと思いますが、有効性検査を入れる瞬間、リポジトリ層がビジネスロジックを処理することにならないでしょうか？
- 初めにリポジトリ層は特別な場合を除きビジネスロジックとは関係がないべきだと定義していました。しかし、有効性検査で特定の行やフィールドを制約する瞬間、リポジトリ層がビジネスロジックを一部処理することになります。一部ではそのロジックがむしろサービス層にあるべきという高見もありました。
などのフィードバックを受け、自分が思いつかなかった部分について知ることができました。
その後、既存のすべてのデータ層だけでなく、一部重要なデータにのみ有効性検証を追加するよう制約条件を修正し、スムーズにそのコード規約を納得させることができました。
3. コード規約は継続的に管理されなければならない。
コード規約を作成した場合、それを継続的に管理する必要があります。細部にわたって作成すればするほど、コード規約の内容が詳細になりますが、修正したり、新技術を導入したりする時に、そのコード規約は迅速に廃止し、新しいコード規約を作成する必要があります。
これは会社の立場でも、チームの立場でも、コード規約を管理する個人の立場でも、全て疲労困憊することがないはずです。
したがって、コード規約を作る際は、該当するコード規約を継続して管理することのできる人材が必要であり、コード規約で指定する範囲や内容について慎重に考慮する必要があります。
それでもコード規約が必要な理由
それにもかかわらず、よく定義されたコード規約は開発速度を向上させる部分があります。
むしろ強力に制約しているため、新しく入社したジュニアの立場では、一度コードレビューで厳しくやられると、次からはどのようにコードを書けば良いのかを学ぶことができます。
良いコード規約は、コードを効率的に書けるようにし、コミュニティとして全員が管理可能なコードになります。
以前に会社で何かのバグが発生したとき、そのバグを発生させたコードを書いた開発者が休暇や退職などの理由で不在であっても、そのコードを迅速に修正することができたのは、コード規約のおかげでした。
コード規約だけでも、「こんなコードがこんな役割を果たすでしょう」という予測可能性のおかげでした。
コード規約の導入
もしコード規約を導入したいなら、次のような部分がヒントになるかもしれません。
リファレンスコード規約を探索
Google ConventionやAirbnb Conventionなどのリファレンスを参考にして、会社に合ったコード規約文書を作成することが良いです。
私はバックエンド開発者として働いていますが、以前はメソッドネーミングのコード規約を指定する際に、Google Cloudのメソッド名の規則を参考にしていました。
一つのヒントは、こういった基盤文書があるとチームメンバーを説得しやすくなるという点です。私だけでなく、Googleのような巨大な開発者たちがこうやってコードを書いているので、我々もこうやって書くべきだということに対する強力な根拠になります。
Github Discussionの活用
Github DiscussionはGithubで提供するコミュニティ機能です。以前にその機能を通じてコード規約を提案し、討論を通じてコード規約導入を決定しましたが、投票、コメント、ラベルなどを通じて様々な提案を一緒に見て検討することができ、便利でした。
ディスカッション例
もちろん欠点はリポジトリに帰属するという点で、以前はOrganization Discussionを用意し、会社全体でそのディスカッションチャンネルを活用しました。
コードレビューを活用する
コードレビューはコード規約が作られるもう一つのチャンネルの一つです。経験上、多くの人のコードレビューの中からコード規約として定着したものが多く、次のようなものがあります。
- 早期リターンパターンを使う
- 変数宣言の後には一行空ける
- ビジネスレイヤーで3回以上のデータレイヤーを呼び出す場合はデータレイヤーの上にコメントを付ける
- 特定のレイヤーから特定のレイヤーにデータを渡す場合はDTOを使う
よく覚えていませんが、これら以外にも多くのコード規約はコードレビューを通じて作られました。
一度の提案でうまくいかなくても挫折しない
人間なので、当然ながら提案が却下されコード規約として漏れる経験をすると挫折することがあります。
しかし、短いですが経験上、却下されたコード規約に関連する問題が発生して再び取り上げられ、採択されることになったり、別の良い代案が生まれてコード規約にしなくても解決されることがありました。
したがって、一度提案でうまくいかなかったからといって挫折せずに、様々な方法を試してみるのが良いです。
採択されなかった後、もしその部分で問題が再び発生しなかったなら、そのコード規約は逆に過度なコード規約で開発チームの生産性を落とす余地があったことを知るべきです。
コード規約は開発者のコードを強制する非常に強力なコード制約であるため、どのコード規約は効果的に機能するが、あるコード規約はコードの読みやすさや効率性を損なうことがあることを理解しておく必要があります。
コード規約はコストが大きな選択ということを覚えておく
できる限りコード規約は特定の論題に対して最後の手段として考慮するのが良いです。
上記で扱った多くの理由により、コード規約はコストが大きな選択であることを覚えておくべきです。
むしろその問題を解決する他の自動化ツールや開発ツール、Linter、フォーマッタなどを通して自動化する方が効率的であることがあるため、その部分に対する考慮が優先されるべきです。