分かりやすいコードの書き方

第５話：コーディング規約の作り方

（最終更新日：2025.4.13）

コーディング規約を作ろう！

「この関数名、他のと書き方違わない？」「このインデント見づらいな」

チームで開発していると、小さなコードのスタイルの違いが積み重なって、可読性を損なうことがある。 そんなときに力を発揮するのが「コーディング規約」だ。 今回はコーディング規約の必要性と、具体的にどんな項目をどのように決めるべきかを紹介する。

１.なぜコーディング規約が必要か

なぜ、コーディング規約が必要か。その答えを以下の四項目にまとめる。

• 可読性の統一：誰が書いても同じようなスタイルになることで、コードの読みやすさが大幅に向上
• レビューが楽：スタイルの議論ではなく、ロジックや設計に集中できる
• バグの予防：フォーマットや命名の統一で、思わぬミスやバグが起きにくい
• 自動化できる：ツールでチェックや整形ができるため、手間をかけずに徹底

このような多くのメリットを享受できるため、コーディング規約を書くことが大事だ。 実際、ある程度スキルがある人たちでも、規約があるか無いかで、そのプロジェクトのコーディングの質、統一性が大きく変わることを体感している。 ぜひ、時間を惜しまず作ってみよう。

２.最低限決めるべきルール

最低限決めるべきルールは、これまで述べてきたことの総合になる。 「関数、変数、定数、クラスの書き方は？」「キャメルケースかスネークケースか？」「ブール値の接頭辞は？」 「許される行数は？」「インデントの数、中括弧の位置は？」など、統一すべきルールを決める。 使用できるリソース（保存容量、メモリなど）を考え、運用上必要な設定も決める。 初めにこれなら大丈夫というルールで運用し、問題があれば改善する。チームとして同じ書き方を徹底することが大事だ。 下記に「関数、変数、定数、クラスの書き方」を示す。

関数、変数、定数、クラスの書き方

要素	命名例
関数	getUserProfile()
変数	userName
定数	MAX_RETRY_COUNT
クラス	UserManager

次に「コメントの書き方」を示す。 コメントは、//を使うか、/* */を使うかなどになる。 また、コメントタグを使うかなどである。

また、ファイル構成、ディレクトリ構成なども定義しておく。 どのディレクトリに何のファイルを置くかを決める。ディレクトリの名前で、何を置くディレクトリかが想像できると良い。 下記にdjangoの例を示す。フレームワークで大体指定されているが、下記のようになる。

３.実例

コーディング規約を作る際、一から全部自分たちで決める必要はない。 インターネット上で公開されているもので、既に優秀なコーディング規約があるからだ。 その規約を参考にしつつ、自分たちの運用にあった規約に編集していこう。

例えば、C++なら「Google C++ Style Guide」、 JavaScript,TypeScriptなら「Airbnb JavaScript Style Guide」、 PythonならPEP8（Python公式のスタイルガイドでVSCodeなどのIDEにアドオンできる）を適用する。

４.チームで規約を徹底する方法

チームで規約を徹底するには、以下のような手順を踏むとよい。

1. チーム全員で合意を取る
   • 自分の好みではなく、チームとしての合意が大事
   • なるべく既存ガイドに準拠し、議論を減らす
2. ドキュメントとして明文化する
   • CONTRIBUTING.md や docs/coding-style.md に記載
   • いつでも確認できるように共有リポジトリに置く
3. 自動化ツールを活用する
   • フォーマッタ：clang-format, prettier, black など
   • 静的解析：cpplint, eslint, pylint, clang-tidy
4. コードレビューで習慣づける
   • 最初は多少の例外もOK。レビューの中で徐々に浸透させる
   • 指摘するだけでなく、どう直すべきかも一緒に共有する

５.まとめ

今回はコーディング規約の作り方について解説した。 コーディング規約は「分かりやすいコード」をチームで書くための共通言語である。 規約の中でも、命名・インデント・コメント・構成の4つは最低限決めておこう。 そして、ルールを文書化し、ツールで自動チェックできるようにするのが理想である。 作ったルールを遵守することで、将来的に楽に他の人のコードを読めるようになれば幸いだ。

▼参考図書、サイト

 「リーダブルコード」　Dustin Boswell、Trevor Foucher　著、角 征典　訳　オライリー