コーディング規約の作り方｜テンプレートと自動チェックの設定

コーディング規約は、チームでコードの書き方をそろえるための決まりです。 作るときのコツは、「ツールで自動で守らせる部分」と「人がレビューで見る部分」を分けることです。書式や命名のように機械で判定できるものを文章で長く書くと、読まれず、守られません。

この記事では、書式の崩れたコードをフォーマッタにかけ、直ったもの・直らなかったものを確かめました。

確認環境：Prettier 3.9.10＋prettier-plugin-java 2.11.0、Ruff 0.17.0（Linux）で確かめました（確認日 2026年10月12日）。

1. まず「土台にする規約」を決める

一から書くより、公開されている規約を土台にして、チームで変えたいところだけを書き足すほうが早く、抜けも少なくなります。

Google Java Style Guide には、たとえば次のように書かれています。

インデントを4スペースにしたいなど、土台と違う決まりは「変更点」として一覧にしておくと、新しく入った人が迷いません。

2. 規約に書く項目（テンプレート）

ツールで守らせる項目は「ツールと設定ファイルの場所」だけを書き、文章は人が判断する項目に使います。

「なぜその決まりなのか」を1行添えると、守られやすくなり、例外の判断もしやすくなります。

【例外】Exception をまとめて catch して何もしないことは禁止。
  理由：障害の原因がログに残らず、調査できなくなるため。
  例外：外部ライブラリが Exception しか投げない場合は、ログを出したうえで catch してよい。

ログと例外の決め方は、関連記事「ログレベルの使い分け｜ERROR・WARN・INFO・DEBUGの判断基準とログ設計」「エラー処理設計の方針｜業務エラーとシステムエラーの分類表とテンプレート」で、名前の付け方は「変数名・関数名の付け方｜命名規則と言語別のルール」で扱っています。

3. 書式はフォーマッタに任せる（再現）

次の Java のコードを、Prettier（prettier-plugin-java）にかけました。

package com.example;
import java.util.*;
public class OrderService{
  private static final int max_items=100;
  public List<String> FindNames(List<Order> orders){
    List<String> result=new ArrayList<>();
    for(Order o:orders){ if(o.getStatus()=="PAID"&&o.getTotal()>0){result.add(o.getCustomerName());} }
    return result;
  }
  public int calc(int a,int b){try{return a/b;}catch(Exception e){return 0;}}
}

設定ファイル（.prettierrc）です。

{
  "plugins": ["prettier-plugin-java"],
  "printWidth": 100,
  "tabWidth": 4
}

npx prettier --check src/      # 崩れていれば終了コード1（CI で使う）
npx prettier --write src/      # 直す

--check は Code style issues found と表示して終了コード1になり、--write のあとは次のようになりました。

package com.example;

import java.util.*;

public class OrderService {

    private static final int max_items = 100;

    public List<String> FindNames(List<Order> orders) {
        List<String> result = new ArrayList<>();
        for (Order o : orders) {
            if (o.getStatus() == "PAID" && o.getTotal() > 0) {
                result.add(o.getCustomerName());
            }
        }
        return result;
    }

    public int calc(int a, int b) {
        try {
            return a / b;
        } catch (Exception e) {
            return 0;
        }
    }
}

見た目は整いましたが、中身の問題は1つも直っていません。

フォーマッタは「書式」、リンターは「決まり」、レビューは「意味」を受け持つ、と分けて考えます。

4. 決まりはリンターで指摘させる

Java：Checkstyle のチェック名

Java では Checkstyle がよく使われます。上の表の問題に対応するチェックは次のとおりです（説明は Checkstyle のドキュメントの原文）。

設定ファイル（checkstyle.xml）に、チームで使うチェックを並べます。

<module name="Checker">
  <module name="TreeWalker">
    <module name="AvoidStarImport"/>
    <module name="ConstantName"/>
    <module name="MethodName"/>
    <module name="StringLiteralEquality"/>
    <module name="IllegalCatch"/>
    <module name="EmptyCatchBlock"/>
  </module>
</module>

同じ問題を Ruff（Python）で確かめた

リンターが実際にどう指摘するかを、同じ種類の問題を含む Python のコードで確かめました。

from os.path import *

MaxItems = 100

def FindNames(orders):
    result = []
    for o in orders:
        if type(o) == dict and o["status"] == "PAID":
            result.append(o["name"])
    return result

def calc(a, b):
    try:
        return a / b
    except Exception:
        return 0

# ruff.toml
line-length = 100

[lint]
select = ["E", "F", "N", "BLE", "B"]

$ ruff check order_service.py --output-format concise
order_service.py:1:1: F403 `from os.path import *` used; unable to detect undefined names
order_service.py:5:5: N802 Function name `FindNames` should be lowercase
order_service.py:8:12: E721 Use `is` and `is not` for type comparisons, or `isinstance()` for isinstance checks
order_service.py:15:12: BLE001 Do not catch blind exception: `Exception`
Found 4 errors.

import・命名・型の比べ方・例外の握りつぶしの4つが、行番号つきで指摘されました。 終了コードは1なので、CI でそのまま止められます。

5. CIとエディタで「守るのが当たり前」にする

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

[*.java]
indent_style = space
indent_size = 4

既存のコードに後から入れるときは、一度に全部を直すと差分が大きくなりすぎます。 書式だけを直すコミットを1回に分ける、リンターは新しく変えたファイルから対象にする、など段階を決めて入れます。

6. レビューで見ること（ツールでは見られないこと）

レビューの観点は、関連記事「コードレビューの観点チェックリスト｜優先順位と伝え方」で扱っています。

よくある質問

Q. 規約は何ページくらいがいいですか。 A. 書式と命名の形をツールに任せると、文書に残るのは「人が判断する決まり」だけになり、数ページに収まることが多くなります。長い規約ほど読まれにくいので、ツールで守れるものは文章から外します。

Q. タブかスペースか、インデントは何文字かで揉めます。 A. 土台にした規約に合わせるか、フォーマッタの既定値に合わせると、議論が短くなります。大事なのは、決めたあとはフォーマッタが自動で守ることです。

Q. 生成AIが書いたコードにも規約を守らせたい。 A. AIが書いたコードも、同じフォーマッタ・リンター・CI を通せば守らせられます。プロジェクトの説明ファイル（CLAUDE.md など）に「フォーマッタとリンターを実行してから終える」と書いておく方法もあります。AIのコードの確かめ方は、関連記事「AI生成コードの確認チェックリスト｜品質とセキュリティ」で扱っています。

Q. 規約を守らない人がいます。 A. 人に注意するより、CI で止める仕組みにするほうが、関係もこじれません。ツールで止められない決まりは、レビューの観点表に入れて、誰が見ても同じ指摘になるようにします。

まとめ

• 規約は フォーマッタ（書式）・リンター（決まり）・レビュー（意味） に分けて作る
• 公開されている規約を土台にし、変えるところだけを書き足す
• Prettier で整えても、命名・ワイルドカード import・文字列の ==・例外の握りつぶしは残った
• リンター（Checkstyle・Ruff など）は 行番号つきで指摘し、終了コード1で CI を止められる
• 文書には 「なぜその決まりか」 を1行添え、CI で守るのを当たり前にする

参考・出典

確認日はいずれも 2026年10月12日です。

• Google Java Style Guide：https://google.github.io/styleguide/javaguide.html
• PEP 8（Style Guide for Python Code）：https://peps.python.org/pep-0008/
• Checkstyle「Checks」：https://checkstyle.org/checks.html
• Prettier ドキュメント「CLI」（--check・--write）：https://prettier.io/docs/cli
• prettier-plugin-java 2.11.0（npm）：https://www.npmjs.com/package/prettier-plugin-java
• Ruff ドキュメント「Rules」：https://docs.astral.sh/ruff/rules/
• EditorConfig：https://editorconfig.org/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。