Java | 基礎文法：コーディングスタイル

Java Java
スポンサーリンク

コーディングスタイルの全体像

コーディングスタイルは「読みやすさ」「一貫性」「変更に強い設計」をコードに刻むための約束事です。Java では命名・インデント・括弧・行の構成・コメント（Javadoc）・例外・ロギング・API設計指針までを揃えることで、チームの誰が読んでも同じ理解になる状態を作ります。重要なのは「見た目を揃える」だけでなく、意図が伝わる命名と、壊れにくい設計をセットで守ることです。

命名のスタイルと意図の伝え方

識別子の基本形（クラス・メソッド・フィールド）

クラス名は名詞で PascalCase（例：OrderService）。メソッドは動詞で camelCase（例：findById）。フィールドは意味がわかる名詞（例：totalAmount）。定数は大文字＋アンダースコア（例：MAX_RETRY）。1文字名は一時的なループ変数以外では避け、略語は一般的なもの（ID、URL）以外は展開します。

public final class OrderService {
    private static final int MAX_RETRY = 3;
    public Order findById(String id) { /* ... */ }
    public void submit(Order order) { /* ... */ }
}
Java

真偽値・コレクションの命名

真偽値は is/has/can で始める（isActive, hasItems）。コレクションは複数形・内容が分かる名（orders, userIds）。Map はキーと値を示す（priceByProductId）。名前から型を推測できると、コメントが少なくても意図が伝わります。

レイアウトと書式：読める形を固定する

括弧・インデント・空行

ブロックは開き括弧を行末、閉じ括弧は改行で揃えます。インデントはスペース4で統一し、論理的な塊の間に空行を入れて視線誘導します。一行は長くしすぎず、120文字程度を上限にします。

if (hasText) {
    process(input);
} else {
    warn("empty");
}
Java

1行1責務と早期リターン

複雑なネストを避け、前提を満たさない場合は早期に return/throw で抜けます。「左に浅く、右に深く」を避けると、目で追いやすくなります。

public String normalize(String s) {
    if (s == null || s.isBlank()) return "";
    return s.trim().toUpperCase();
}
Java

import とクラス構成の順序

import は必要なものだけ。ワイルドカードは原則避け、IDEの最適化を使います。クラス内の宣言順は「定数→フィールド→コンストラクタ→公開メソッド→非公開メソッド」で安定させます。

API 設計と安全性（重要ポイントの深掘り）

null 取り扱いの方針

引数で null を許さないなら入口で明示的に検証し、例外メッセージで意図を伝えます。戻り値に「値なし」を表すなら Optional を使うと、呼び手が忘れずに分岐できます。

import java.util.Objects;
import java.util.Optional;

public Optional<User> findUser(String id) {
    Objects.requireNonNull(id, "id must not be null");
    /* ... */ return Optional.empty();
}
Java

equals と hashCode の整合

値オブジェクトは equals/hashCode を対に設計します。コレクションのキーにするなら不変（immutable）を基本にし、可変フィールドで同値性が変わらないようにします。record はこの用途に適しています。

public record Money(int amount, String currency) {}
Java

例外・契約の表明

「呼び手で回復可能」な失敗はチェック例外で表し、実行時例外は契約違反の早期検知に使います。例外の包み直しでは cause を保持して、原因連鎖を途切れさせないようにします。

try {
    repo.save(order);
} catch (java.sql.SQLException e) {
    throw new IllegalStateException("保存失敗 id=" + order.id(), e);
}
Java

ロギング・コメント・Javadoc

ロギングの粒度とメッセージ

ログは「何が・どこで・どの入力で」を固定し、同じ失敗を重複して記録しない（下位と上位で二重出力しない）。テンプレートにキー＝値で入れると機械でも人でも読めます。

log.error("read_failed path={} reason={}", path, e.toString());
Java

コメントは「なぜ」を書く

コードが読みやすければ「何を」はコードが語ります。コメントは「なぜこの設計にしたか」「意図的なトレードオフ」だけに絞り、古くなったコメントは消してコードを最新の真実に保ちます。

Javadoc で契約を明文化

公開メソッドには「前提条件・戻り値・例外・スレッドセーフ性」を書いて契約を明確にします。IDEでツールチップに出るため、利用者の理解が早くなります。

/**
 * 与えられたIDのユーザーを検索する。
 * @param id null不可
 * @return 見つかった場合はユーザー、見つからなければ Optional.empty()
 */
public Optional<User> findUser(String id) { /* ... */ }
Java

テストしやすい構造と小さなメソッド

小さな単位に分ける

一つのメソッドは「一つの目的」に絞り、10～30行程度を目安に保ちます。長くなったら抽出（Extract Method）で分割します。副作用のある処理（I/O、DB）と純粋なロジックを分離するとテストが楽になります。

public int taxedTotal(int subtotal, double rate) {
    int tax = calcTax(subtotal, rate); // ロジックを分離
    return subtotal + tax;
}
private int calcTax(int subtotal, double rate) {
    return (int) Math.round(subtotal * rate);
}
Java

依存の注入で差し替え可能に

外部サービスはコンストラクタやセッターで注入し、テスト時にスタブへ差し替えられる形にします。new で直接作るより、拡張性とテスト容易性が上がります。

フォーマッター・静的解析の活用

自動整形を前提にする

IDEやビルドでコードフォーマッター（Google Java Format など）を使い、誰が書いても同じ見た目になるようにします。手作業の整形コストをゼロにすると、内容に集中できます。

静的解析で習慣化する

NullAway、SpotBugs、Checkstyle などでルール化し、PRやビルドで自動チェックします。「人が目視で見逃す」種類の問題（未初期化、NPEリスク、命名逸脱）を機械で弾くと品質が安定します。

例題で身につける

例 1: 命名と早期リターンで読みやすさを確保

public String userLabel(User u) {
    if (u == null) return "(unknown)";
    String name = u.name().trim();
    if (name.isEmpty()) return "(no name)";
    return name.toUpperCase();
}
Java

例 2: Optional と Javadocで契約を見える化

/**
 * 指定メールでユーザーを検索する。
 * @param email null不可
 * @return 見つかったユーザー、未発見なら empty。I/O失敗時は例外。
 * @throws IOException バックエンドの読込に失敗
 */
public Optional<User> findByEmail(String email) throws IOException { /* ... */ }
Java

例 3: Comparator の安全な設計と読みやすさ

record Product(String id, String name, int price) {}
java.util.Comparator<Product> byPriceThenName =
    java.util.Comparator.comparingInt(Product::price)
                        .thenComparing(Product::name);
Java

仕上げのアドバイス（重要部分のまとめ）

命名で意図を伝え、レイアウトで読みやすさを固定し、早期リターンで深いネストを避ける。APIは null方針・契約・例外を明文化し、equals/hashCode は不変・整合で壊れないように設計する。コメントは「なぜ」を、Javadocは契約を。自動整形と静的解析で習慣を仕組みにして、テストしやすい小さなメソッドへ分割する——この型が身につけば、あなたのコードは「誰が読んでも同じ理解」に到達します。

スポンサーリンク
タイトルとURLをコピーしました