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、意図は近く: 役割分担で迷子を防ぐ。
ひとこと
今の理解を、未来の自分に手渡すのがコメント。完璧じゃなくていいので、「なぜ」を短く残すことから始めましょう。
