コメントは「プログラムに書く自分（や他人）へのメモ」です。実行には影響しないけど、読みやすさ・保守性をグーンと上げる 超重要スキル。初心者向けに、なぜ必要か、どう書くか、良いコメント／悪いコメントの例、最後に練習問題（解答付き）まで全部まとめます。
1. なぜコメントを書くのか（超シンプルに）
- 何をしているか分かる：コードだけだと「どういう意図か」が不透明なことがある。
- なぜその実装にしたか書ける：将来の自分が「なんでこうしたっけ…？」とならない。
- チーム開発での説明になる：他の人が読んで理解しやすい。
- ドキュメント生成に使える：Javadoc を使えば自動で仕様書を作れる。
2. Javaのコメントの3種類（実例で覚える）
A. 単一行コメント (//)
その行の末尾までコメントにする。ちょっとした補足に最適。
// i はループ用カウンタ（1から10まで）
for (int i = 1; i <= 10; i++) {
sum += i; // 現在の合計に i を足す
}
B. 複数行コメント (/* ... */)
数行に渡る説明や、一時的にコードを無効化するときに使う（ただし無効化は控えめに）。
/*
この部分は合計を計算する処理です。
入力は 1 から 10 の整数と仮定しています。
*/
int sum = 0;
C. Javadocコメント (/** ... */) — ドキュメント用
クラスやメソッドの「仕様」を書く。javadocツールでHTMLドキュメントを生成できる。
/**
* 1〜n の合計を返します。
*
* @param n 合計する最終の整数（正の整数を想定）
* @return 1 から n までの合計
* @throws IllegalArgumentException n が負の場合
*/
public static int sumUpTo(int n) {
if (n < 0) throw new IllegalArgumentException("n must be non-negative");
int sum = 0;
for (int i = 1; i <= n; i++) sum += i;
return sum;
}
3. 実際のフルサンプル（.java として実行可能）
/**
* ExampleComments
*
* サンプルプログラム：コメントの使い方を示します。
*/
public class ExampleComments {
public static void main(String[] args) {
int n = 10; // 例として 1〜10 の合計を計算
int total = sumUpTo(n); // メソッド呼び出しで合計を取得
System.out.println("1から" + n + "までの合計は " + total + " です。");
}
/**
* 1から指定された n までの合計を計算して返す。
* @param n 最終の整数（1 以上を想定）
* @return 合計値
*/
public static int sumUpTo(int n) {
int sum = 0;
// 各 i を順に足していく
for (int i = 1; i <= n; i++) {
sum += i; // 現在の i を合計に加える
}
return sum; // 計算結果を戻す
}
}
このファイルを ExampleComments.java として保存し、javac ExampleComments.java → java ExampleComments で動きます。
4. 「良いコメント」と「悪いコメント」の例（分かりやすく）
悪いコメント（単にコードを繰り返す／ノイズになる）
i++; // i を 1 増やす
→ これはコードそのまま。無意味。コメントは「なぜ増やすのか」「目的」を書くべき。
良いコメント
// 次のループで次のページへ移動するためのカウンタを更新
i++;
→ 目的がわかる。将来の自分に優しい。
悪いコメント（古くて誤情報）
// 現在は n は常に 10 のはず
→ 実際に将来 n が変わるとこのコメントが誤解を生む。コードとコメントを一緒に保守すること。
5. コメントのベストプラクティス（初心者向けチェックリスト）
- コードが「何をするか」より「なぜそれをするか」を短く書く。
- 書きすぎず、要点だけ（1〜2行で済むならそれでOK）。
- 命名（変数名・メソッド名）を工夫してコメントを減らす：
int countよりint pageCountの方が説明的。 - Javadoc は公開API（メソッド・クラス）の説明に使う。
@param,@returnを忘れずに。 TODO:やFIXME:を使って「後でやること」を残す（IDEで検索しやすい）。例：// TODO: エラー処理を追加する- コメントが古くならないよう、コードを変更したらコメントも更新する習慣をつける。
6. よくある質問（FAQ）
- Qコメントはどのくらい書けばいい？
- A
「読んで理解するのに必要な最低限＋設計の意図」が目安。コードそのものが明確なら細かいコメントは不要。
- Qコメントで日本語はOK？英語は？
- A
チームや公開先に合わせて。学習中や日本語のチームなら日本語でOK。将来のポートフォリオは英語にすると良い場面も。
- Qコメントで実装の詳細を書くべき？
- A
アルゴリズムの意図やトリッキーな箇所は書く。詳細な行単位の説明は冗長になりやすい。
7. 練習問題（自分で手を動かしてみよう） — 解答付き
問題1（簡単）
次のコードに良いコメントを3箇所くらい入れてみてください。
int[] arr = {3, 1, 4, 1, 5};
int max = arr[0];
for (int i = 1; i < arr.length; i++) {
if (arr[i] > max) {
max = arr[i];
}
}
System.out.println(max);
模範解答例（要点）
// 配列の最大値を探す例
int[] arr = {3, 1, 4, 1, 5};
int max = arr[0]; // 最初の要素を仮の最大値に設定
for (int i = 1; i < arr.length; i++) {
// 現在の要素が仮の最大値を超えたら更新
if (arr[i] > max) {
max = arr[i];
}
}
System.out.println(max); // 最大値を出力
問題2（Javadoc を使う）
multiply(int a, int b) というメソッドを作り、Javadocで説明を書いてください。
解答例
/**
* 2つの整数を掛け算して返す。
* @param a 左の値
* @param b 右の値
* @return a と b の積
*/
public static int multiply(int a, int b) {
return a * b;
}
問題3（実践）
次のコメントは改善できますか？改善してみてください。
// 変数の初期化
int x = 0;
改善例
// ユーザーの合計スコアを格納する初期値（まだ得点がないので 0）
int userScore = 0;
→ 変数名を説明的にしてコメントの意味を明確に。
問題4（応用）
次のメソッドに Javadoc と短い内部コメントを加え、何をしているか説明してください。
public static boolean isPrime(int n) {
if (n <= 1) return false;
for (int i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}
解答例
/**
* 与えられた整数が素数かどうかを判定する（単純な方法）。
* @param n 判定する整数
* @return n が素数なら true、そうでなければ false
*/
public static boolean isPrime(int n) {
if (n <= 1) return false; // 1以下は素数ではない
for (int i = 2; i < n; i++) { // 2 から n-1 まで割り切れる数を探す
if (n % i == 0) return false; // 割り切れたら素数ではない
}
return true; // 割り切れる数がなければ素数
}
（注：アルゴリズムの改善点をコメントで残しておくのもGood。例：// ここは sqrt(n) まで調べれば十分）
問題5（レビュー）
他人が書いたコメントが古くなっていたらどうしますか？
答え（考え方）：コードを修正したときに一緒にコメントも更新する。コメントが正しいか確認するために、短いテストや動作確認を行う。
まとめ（初心者がまずやること）
- 小さなプログラムでもコメントを入れる習慣をつける。
- 「なぜ」を書く。コードの「何」を繰り返さない。
- メソッドやクラスにはJavadocを書いておく（あとで助かる）。
- 定期的にコメントを見直して、古いコメントは削除・更新する。