Web制作、Web開発の歩き方

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

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

（最終更新日：2025.4.13）


分かりやすいコード

この記事は5分で読めます！
（絵が小さい場合はスマホを横に）

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

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

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



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

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

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

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

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

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

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

要素 命名例
関数 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　著、角 征典　訳　オライリー

How to Write Understandable Code Episode 5: How to Create a Coding Convention (Last updated: 2025.4.13) Understandable Code You can read this in 5 minutes! (If the image is small, try rotating your phone horizontally) Let’s create a coding convention! “Doesn’t this function name look different from the others?” “This indent is hard to read.” When developing as a team, small differences in coding style can accumulate and hurt readability. That’s where a “coding convention” becomes valuable. In this article, we’ll cover why coding conventions are necessary and how to decide on specific rules. [Contents] Why a Coding Convention is Needed Essential Rules to Define Examples How to Enforce Conventions as a Team Summary 1. Why a Coding Convention is Needed Here are four key reasons to adopt a coding convention: Consistent readability: Code becomes easier to read when everyone uses the same style. Easier reviews: You can focus on logic and design instead of style debates. Fewer bugs: Consistent formatting and naming reduce mistakes and bugs. Automation-friendly: Tools can enforce and format code automatically with minimal effort. These benefits make coding conventions essential. Even experienced developers notice significant improvements in code quality and consistency when conventions are in place. Take the time to create one. 2. Essential Rules to Define The rules you need to define combine everything discussed so far. Decide on naming styles for functions, variables, constants, classes—camelCase or snake_case? Boolean prefixes? Maximum line lengths? Indentation size and bracket placement? Consider your available resources (storage, memory, etc.), and define operational settings accordingly. Start with a “good enough” version, and improve as needed. The key is consistency across the team. Naming Examples for Functions, Variables, Constants, and Classes Element Example Function getUserProfile() Variable userName Constant MAX_RETRY_COUNT Class UserManager Next is “how to write comments.” Decide whether to use `//` or `/* */`, and whether to use comment tags. Comment Style Also define file and directory structure. Decide which files go into which directories. Directory names should be self-explanatory. Here’s an example from Django. Most frameworks already have a structure, like this one: Directory Structure 3. Examples You don’t have to start from scratch when creating a coding convention. There are excellent public style guides available online. Use them as a reference and tailor them to your needs. For example: For C++: Google C++ Style Guide For JavaScript/TypeScript: Airbnb JavaScript Style Guide For Python: PEP8 (official Python style guide, supported by VSCode and other IDEs) 4. How to Enforce Conventions as a Team Follow these steps to ensure your team adheres to the rules: Reach team-wide agreement Personal preferences don’t matter—team consensus does. Stick to well-known guides to reduce debate. Document the rules Write them in CONTRIBUTING.md or docs/coding-style.md Store them in a shared repository for easy access. Use automation tools Formatters: clang-format, prettier, black, etc. Static analyzers: cpplint, eslint, pylint, clang-tidy Promote through code reviews Allow minor exceptions at first. Let habits form over time. Don’t just point out issues—suggest how to fix them. 5. Summary This article explained how to create a coding convention. A coding convention is a shared language for teams to write “understandable code.” At a minimum, define rules for naming, indentation, comments, and structure. Ideally, document these rules and enable automatic enforcement with tools. Sticking to your rules will make it much easier to read others’ code in the future. ▼References  “Readable Code” by Dustin Boswell and Trevor Foucher, translated by Masanori Kado, O'Reilly Japan