コードガイド
ジュニア開発者がコード規約を初めて始めるとき
私が初めて会社に入ったときは、もどかしいことがたくさんありました。 特にコードを見ると、なぜこんなにif文とfor文がネストされているのか、なぜこんなにコードが乱雑なのか、なぜこんなに変数名が変なのか、などです。 会社に入って過ごしていると、もちろん人の能力が不足しているからという納得しやすい理由を挙げることができますが、実務経験が積もれば積もるほど臨機応変に対応しなければならないことや既存の設計と異なる方向の企画など、本人が開発していてもさまざまな理由でコードが乱雑になる場合が多いです。 そのようなことに助けを与えるのが、協業時のコード規約ですが、その理由は強力なルールを通じてコードの品質をかなり短期間で向上させることができるからです。（特にコードレビュー文化がある場合、肯定的に定着する可能性が非常に高いです。） この文では短いですが経験を通してコード規約を導入する際にどのような点を考慮したのか、その中でジュニア開発者がどのようにしてコード規約を提案し、会社に適用したのかを書いてみようと思います。 コード規約はなぜ必要なのか？ 実際、コード規約というものは2人以上で開発を行うとき意味があります。 1人開発の場合、本人がすべてのパートに責任を持ち開発を行うでしょう。また、本人の規則ですのでコード規約にこだわる必要はないと思います。 しかし、2人以上での開発を視野に入れている、またはすでに2人以上で開発している場合は、それぞれのコードスタイルが異なるため、プロジェクトに参加する人数が多くなればなるほど混乱する可能性があります。 コード規約は最も直接的にコードにルールを付与するものであるため、コードの品質を一定以上の水準に引き上げることができます。また、コード規約を熟知している人員が多くなればなるほど、コードがまるで1人が書いたかのように読めるため、コードの一貫性を維持し、誰もが予測可能なコードを書くことができるようになります。 ただし、コードにルールを課す行為であるため、プロジェクトメンバーの抵抗や、コード規約を作る理由についての説得が必要であり、この文ではそれについてどのようにアプローチしたのかについて書いてみようと思います。 コード規約を導入する際の障害 個人的に全員が大企業に勤めているわけでもなく、スタートアップ、中規模の企業に勤めていても、体系的なコード規約を通じて開発を行うことを見るのは容易ではないと思います。その理由については、いくつかの理由があるでしょう。 1. 初期スタートアップの場合、会社（代表）が望まない。 初期スタートアップ、つまりまだ収益を出していない会社の立場では、コード規約を作り維持することも費用の問題に直結すると認識する場合が多いです。 私はその部分に関して一部肯定しつつ、一部は否定する立場です。 実際にコード規約を記した文書があったとしても、言語のバージョンがアップグレードされたり、新しいツールを導入するなど、コード規約の管理が疎かになると、その存在意義が薄れることがあります。 初期スタートアップの場合、そういう文書を作るよりも一行のコードが、一つの機能がより重要だと考える場合が多く、私はコード規約の管理コストがかなり大きいと考えているため、ある程度その部分について制約が伴うと思います。 JSPを使用していた会社がSpringに変更する際にコード規約文書を再作成するコストを負担できるでしょうか？DB接続、コントローラの書き方、SSR方式からRestful APIへの変更など、確固たるコード規約文書が共にあったとすれば、変化に対するコストも大きくなることでしょう。 ただし、初期スタートアップも徐々に規模が大きくなり、開発する人数が増えるにつれて、コードには様々な人の直感が反映されたコードが書かれることになります。こうしたコードは、作成者以外にとっては保守が難しくなり、create, getなどの単純な命名であっても、意図や動作を推測しにくくなる場合があります。 （実際にcreateで始まったのに、あるメソッドはDB保存を、あるメソッドは一時的なエンティティを返す役割だけをするという場合もありました。） これらが長く続くと、また管理する人が退職する場合には保守性が極めて難しくなることがあります。このような場合、初期スタートアップにおいても一部の必須項目についてコード規約を導入するのが良いと考えます。 2. コード規約は皆が納得しなければならない。 ジュニア開発者として痛切に感じたことの一つは、自分が特定の方式を良いと思っても、他の人がそれを気に入らなければ、それをコード規約にするのは難しいということです。 特にコード規約を夜を徹して作ったとしても、それを開発者が従わないなら、ただ自分の体力を消耗したに過ぎないのです。 したがって、コード規約は生まれたときから同僚開発者の協議が必要であり、コード規約の必要性自体を開発者に納得させる必要があります。 以下は、私がコード規約を作るために納得させた一連の過程を例に記述したものです。 以前、あるサービスを提供していたとき、サービス層でリポジトリ層にフィルタリングするコードを 適用せず、ラベル付けしたすべてのデータを消してしまうところでした。(もちろん、プロダクションではありませんでした。) その後、リポジトリで全データを条件なしに修正または削除しないように有効性検査をしようと提案しましたが、このようなフィードバックを受けました。 初めて発生したケースを防ぐためにコード規約として導入するには、コードを作成するコストが増加しないでしょうか？ 正しい指摘でした。すべてのデータ層に有効性の検査を入れると、開発時間だけでなくテストコードを作成する際にも時間がよりかかるでしょう。 ビジネスロジックとは無関係なことがリポジトリ層の目的だと思いますが、有効性検査を入れる瞬間、リポジトリ層がビジネスロジックを処理することにならないでしょうか？ 初めにリポジトリ層は特別な場合を除きビジネスロジックとは関係がないべきだと定義していました。しかし、有効性検査で特定の行やフィールドを制約する瞬間、リポジトリ層がビジネスロジックを一部処理することになります。一部ではそのロジックがむしろサービス層にあるべきという高見もありました。 などのフィードバックを受け、自分が思いつかなかった部分について知ることができました。 その後、既存のすべてのデータ層だけでなく、一部重要なデータにのみ有効性検証を追加するよう制約条件を修正し、スムーズにそのコード規約を納得させることができました。 3. コード規約は継続的に管理されなければならない。 コード規約を作成した場合、それを継続的に管理する必要があります。細部にわたって作成すればするほど、コード規約の内容が詳細になりますが、修正したり、新技術を導入したりする時に、そのコード規約は迅速に廃止し、新しいコード規約を作成する必要があります。 これは会社の立場でも、チームの立場でも、コード規約を管理する個人の立場でも、全て疲労困憊することがないはずです。 したがって、コード規約を作る際は、該当するコード規約を継続して管理することのできる人材が必要であり、コード規約で指定する範囲や内容について慎重に考慮する必要があります。 それでもコード規約が必要な理由 それにもかかわらず、よく定義されたコード規約は開発速度を向上させる部分があります。
2024年5月20日
ケーススタイルについて知ろう (Camel Case? Pascal Case? Kebab Case?)
今日は会社でも投稿したことのある記事の一つです。 コーディングを新しく始める方々にガイドしたいことがあるので、そういう部分だけを集めて今後は Code Guide というタグをつけて投稿しようと思います！ コーディングスタイル 一人で開発するのであれば何の問題もありませんね。最近ではほとんどの言語がUTF-8という文字エンコーディングをサポートしているので、コードに日本語を使うこともできます。 特に 変数名 や 関数名 、 クラス名 など開発者が自由に名付けられるものは、理論的には中国語であろうと日本語であろうと問題ありません。 それではなぜほとんどのコーディングは英語で書かれるのでしょう？ 少し話が逸れますが、英語でのみ動作するモジュールや関数があります。 特に C++ のような古い言語の場合、日本語をサポートするには日本語を英語やOSが理解できる文字に変換するパーシングモジュールが別途必要なこともあります。 実はそれ以上に重要なのは、協働する開発者間でコーディングスタイルを合わせるためです。 ある人は日本語、ある人は英語、またある人は中国語で変数名を定義していて、同じ役割をしているのであれば、新しくチームメンバーになった開発者がそのコードを見たときに理解するのが非常に難解なコードになるでしょう。 そのため、開発者間ではコードをどのように名付け、どのように定義するかについての規則が定められており、これをコーディングガイドやコンベンションと呼んでいます。 前置きが長くなりましたね。本題に入りましょうか？ ケーススタイル ケーススタイルは一種のネーミング規則と考えればよいでしょう。 変数や関数名、クラス名を付けるときに、その規則に従って付けるのです。特にスペースに大きく関係しています。 多くの言語がスペースを文法の要素に含んでいるので、そのスペースを置き換える文字をどのように設定するかという悩みが含まれていると考えられます。 ▼ ケーススタイルを面白く表現した画像 ケーススタイルは非常に多いですが、よく使われるケーススタイルは大きく4つの種類があります。 camelCase # キャメルケース PascalCase # パスカルケース snake_case # スネークケース kebab-case # ケバブケース 皆さん気付いていると思いますが、そうです、今書いたコードがケーススタイルの代表的な特徴です。
2022年4月14日