Java | コメント(プログラム中の説明)

Java Java
スポンサーリンク

Javaのコメントの基本を、初心者向けにやさしく

はじめてコードを書くときって、意味がわからない記号だらけで不安になりますよね。コメントは「未来の自分や他人への手紙」。コードの意図を言葉で残しておくことで、迷子になりにくくなります。

コメントは「説明文」。動作には影響しない

  • 役割: コードの目的や理由を文章で補足するための「メモ」。
  • 特徴: 実行に影響しない。書いてもプログラムの結果は変わらない。
  • 使いどころ: なぜこの処理が必要か、前提条件、注意点、未完了のタスクなど。

3つの書き方と使い分け

単一行コメント(その行だけのメモ)

int sum = 0; // 合計値をここで初期化しておく
Java
  • 書式: // 以降がコメント。
  • 用途: 短い補足、変数の意味、1行の意図。

複数行コメント(まとまった説明)

/* 1から10までの数を足し合わせるアルゴリズム
   注意: 今は固定範囲。あとで可変に改善予定 */
int sum = 0;
for (int i = 1; i <= 10; i++) {
    sum += i;
}
Java
  • 書式: /* から */ までがコメント。
  • 用途: まとまった背景説明、注意事項、TODO。

Javadocコメント(クラスやメソッドの公式説明)

/**
 * 数学ユーティリティ
 * 1からnまでの合計を返す。
 * @param n 合計したい最大値(1以上)
 * @return 1からnの合計
 */
public static int sumTo(int n) {
    int sum = 0;
    for (int i = 1; i <= n; i++) sum += i;
    return sum;
}
Java
  • 書式: /** で始める特別なコメント。
  • 用途: クラスやメソッドの仕様を記述。後でドキュメント生成に使える。

具体例で理解する

例1: 「なぜ?」を残すと未来が楽になる

// ユーザー入力が空ならデフォルト名を使う
String name = input.trim();
if (name.isEmpty()) {
    name = "Guest"; // 空欄時に例外を避けるため
}
System.out.println("Hello, " + name);
Java
  • ポイント: 「例外を避けるため」など理由を書いておくと、あとで条件の意味を思い出せる。

例2: バグ回避の背景を書く

/* 並列処理で競合が起きるため、ここは同期化する
   詳細: バージョン1.2で報告された #142 の不具合対策 */
synchronized (cache) {
    cache.put(key, value);
}
Java
  • ポイント: なぜこの重い処理が必要か、背景がわかれば安易に削除されない。

例3: Javadocで「仕様」を明確にする

/**
 * パスワードが有効かを検証する。
 * 条件: 8文字以上、数字と英字を含む
 * 例: "abc12345" -> true
 */
public static boolean isValidPassword(String s) {
    if (s == null) return false; // nullは不可
    if (s.length() < 8) return false;
    boolean hasDigit = false, hasLetter = false;
    for (char c : s.toCharArray()) {
        if (Character.isDigit(c)) hasDigit = true;
        if (Character.isLetter(c)) hasLetter = true;
    }
    return hasDigit && hasLetter;
}
Java
  • ポイント: 仕様・例・前提を書いておくと、使う側が迷わない。

失敗しがちなコメントと、良いコメント

  • 悪い例: コードをそのまま言い換えるだけ i++; // iを1増やす(←冗長)
    • 改善: 「なぜ増やすのか」を書く
    i++; // 次の要素へ進めるため
  • 悪い例: 嘘つきコメント(更新されずにコードとズレる)
    • 改善: ルールを短くしてメンテしやすく。「仕様」はJavadoc、「理由」は近くに短く。
  • 悪い例: すべてにコメント(ノイズ増加)
    • 改善: 自明な処理は書かない。意図・前提・例外・理由に絞る。

練習問題で身につける

練習1: 単一行コメントで「理由」を説明

  • 課題コード:
int retries = 3;
// ここに「なぜ3回リトライするのか」を短く書いてみてください
Java
  • ヒント: ネットワークは一時的に失敗することがある、ユーザー体験のため、など。

練習2: 複数行コメントで「前提と注意」を整理

  • 課題コード:
/* ここに、このバッチ処理の前提(夜間のみ実行、データ量が多い等)と
   注意点(タイムアウト、再実行の可否)を書いてみてください */
processDailyReport();
Java

練習3: Javadocでメソッド仕様を書く

  • 課題コード:
/**
 * ここに仕様(入力の条件、返り値、例外、使用例)を書いてください
 */
public static double average(int[] nums) {
    if (nums == null || nums.length == 0) throw new IllegalArgumentException("empty");
    int sum = 0;
    for (int n : nums) sum += n;
    return (double) sum / nums.length;
}
Java

実務で役立つミニ習慣

  • 目的を1行で: 「何を、なぜ」→ 先頭に短く。
  • TODOは具体的に: 「TODO: 入力検証を追加(null/空/最大長)」。
  • 変更理由を残す: 「2025-10-19: フォーマット変化対応でパースを修正」。
  • 仕様はJavadoc、意図は近く: 役割分担で迷子を防ぐ。

ひとこと

今の理解を、未来の自分に手渡すのがコメント。完璧じゃなくていいので、「なぜ」を短く残すことから始めましょう。

タイトルとURLをコピーしました