コメントを書く
コメントを書く とは
Java の 3 種類のコメント記法と、ゼロ除算を避ける safeDivide メソッドの書き方を学ぶ。
コメントとは
プログラムを書いていると、書いた本人ですら数か月後に「ここ、何やってたんだっけ?」となります。Java に限った話ではありませんが、ソースコードは時間が経つほど読みづらくなるものです。そこで活躍するのがコメントです。コメントとは、ソースコードの中に人間向けの説明を残すための機能のことを言います。コンパイラはコメントを無視するので、javac や java の実行結果には影響を与えません。
コメントはコンパイラに対しては「空白」と同じ扱いになります。つまり何を書いても挙動は変わりません。だからこそ、未来の自分や他の開発者に向けて意図を残す場所として使います。
コメントを使うメリットは次のとおりです。複雑な計算式の意味を残しておける、コードの一部を一時的に無効化できる、Javadoc で API ドキュメントを自動生成できる、といった点が挙げられます。一方で書きすぎは害になります。何でもコメントすればよい、というものではありません。
行コメント //
もっともよく使うのが行コメントです。// から行末までがコメントとして扱われます。短いメモを残したいときに便利です。
Java
public class Solution {
public static int doubleIt(int x) {
// 引数を 2 倍して返す
return x * 2;
}
}上の // 引数を 2 倍して返す は処理に影響しません。return x * 2; だけが実際に実行されます。
行コメントを式の途中に挟む場合、
//からその行末までが消えることに注意が必要です。int a = 1 // メモ\n + 2;のように書くと// メモの部分だけ消え、次行の+ 2は式の続きとして読まれるため動作しますが、意図が伝わりにくくなります。一方int a = 1 + // メモで行を終え、次行に必要なトークンを書き忘れた場合はコンパイルエラーになります。可読性のため、行コメントは文の前後など独立した位置に置くのが一般的です。
ブロックコメント /* ... */
複数行をまとめてコメントにしたいときはブロックコメントを使います。/* で始めて */ で閉じます。途中に改行を入れても構いません。
Java
/*
* このメソッドは検算用です。
* 本番では使いません。
*/
public static int debugAdd(int a, int b) {
return a + b;
}ブロックコメントの中に行コメント // を入れることはできますが、ブロックコメントの ネスト はできません。/* 外側 /* 内側 */ 外側 */ のように書くと、最初の */ で閉じてしまい、後ろの */ が浮いてコンパイルエラーになります。
Javadoc コメント /** ... */
/** で始めて */ で閉じる特殊なブロックコメントは Javadoc と呼ばれます。クラス・メソッド・フィールドの直前に書くと、javadoc コマンドや IDE がそれを読み取って API ドキュメントを自動生成してくれます。@param @return @throws などのタグを使うと、引数や戻り値の説明を構造化できます。
Java
public class Solution {
/**
* 整数の安全な割り算を行う。
* b が 0 のときはゼロ除算を避けて 0 を返す。
*
* @param a 割られる数
* @param b 割る数 (0 のときは 0 を返す)
* @return a / b の整数除算結果。b == 0 のときは 0
*/
public static int safeDivide(int a, int b) {
if (b == 0) {
return 0;
}
return a / b;
}
}Javadoc は単なる装飾ではなく、IDE の補完やマウスオーバーで表示されます。チームで Java を書くなら、
publicなメソッドには必ず Javadoc を付ける、という運用が一般的です。
3 種類のコメントの使い分け
ここまでに登場した 3 種類のコメントを整理すると、用途と適した範囲がはっきりと分かれていることが分かります。次の図を頭に入れておくと、どの場面でどの記法を選べばよいか迷わなくなります。
良いコメントとダメなコメント
コメントには「良いコメント」と「ダメなコメント」があります。良いコメントは「なぜ」を書きます。ダメなコメントは「何をやっているか」をそのまま書いてしまい、コードと重複します。例えば i++; // i を 1 増やす は完全に冗長です。代わりに i++; // 次のページに進める のように、意図を残すと価値が出ます。
また、コードと食い違ったコメントは害悪です。コードを修正したのにコメントを直し忘れると、「コメントには 10 と書いてあるのに実装は 100」のような状態になり、後続の開発者を混乱させます。
整数除算の挙動
このレッスンの課題では int / int の整数除算を扱います。Java では int 同士の / は小数点以下を切り捨てる挙動になります。
10 / 2は510 / 3は3(小数部分は捨てられる)-6 / 2は-310 / 0はArithmeticExceptionで実行時エラー
ゼロ除算は Java では即座にプログラムを止める例外になります。アプリ全体が落ちるのを避けたいなら、割る前に
if (b == 0)で守る、というのが安全な書き方です。
よくある間違い
初心者がコメントで詰まりやすいポイントは次のとおりです。
/*だけ書いて*/を書き忘れる。閉じ忘れるとそれ以降のコード全部がコメント扱いになり、巨大なエラーが出ます。*/を必ずセットで書く癖をつけましょう。//を文の途中に挟む。return a + // 足す \n b;のように書くと、// 足すの部分だけが消えてreturn a + b;として解釈されるため、この例自体はコンパイルも実行もできます。ただし//より後に同じ行で必要なトークンを書いてしまった場合（例int a = 1 + // メモで行を終えてbを書き忘れた構成）は、そのトークンがコメントに飲まれてコンパイルエラーになります。- Javadoc の
/**と通常ブロックの/*を混同する。Javadoc にしたいのに/*で書くと、ドキュメント生成の対象にならず、IDE のホバーにも出てきません。 - コードを直したのにコメントを直し忘れる。コメントが古くなると、コードより信頼できない情報源になります。
やってみよう
Solution.safeDivide(int a, int b) を完成させてください。要件は次のとおりです。
b == 0のときはゼロ除算を避けて0を返す- それ以外は
a / bの整数除算結果を返す - メソッドの直前に Javadoc コメント
/** ... */を必ず入れて、@paramと@returnで引数・戻り値を説明する
例えば safeDivide(10, 2) は 5、safeDivide(10, 0) は 0、safeDivide(-6, 2) は -3 を返します。if で b をチェックし、return で値を返す、というシンプルな構造で書けます。
コメントは「未来の自分への手紙」です。今日書いたあなたのコメントは、半年後の自分や、まだ見ぬチームメンバーを助けます。動くコードを書くだけでなく、読めるコードを書く意識を持って取り組んでみてください。
よくある質問
Q. Java と他言語の文法はどう違いますか？
A. Java は静的型付けで、変数宣言時に型を明示します（int x = 0;）。中括弧でブロックを表し、文末にセミコロンが必要です。Python の動的型付けや JavaScript の柔軟さに慣れていると最初は窮屈ですが、コンパイル時にバグが発見できる安全性がメリットです。
Q. コードが動かないときに最初に見るべき場所は？
A. コンパイルエラーは行番号とエラー種別（cannot find symbol、incompatible types など）が表示されます。実行時例外はスタックトレースの最初の at ... が原因行です。IDE（IntelliJ / VS Code）の警告も丁寧に潰すと、半分のバグは未然に防げます。
Q. Java の習得後に学ぶべき技術は何ですか？
A. 基本構文を抑えたら java-intermediate（コレクション / ジェネリクス / Stream / 例外）に進み、Spring Boot や Web 開発に展開するのが王道です。クラウド時代は Kotlin / Scala への展開も視野に入りますが、まずは Java 標準を固めるのが効率的です。
次のレッスン
次は 第 1 章まとめクイズ で、Java の 3 種類のコメント記法と、ゼロ除算を避ける safeDivide メソッドの書き方を学ぶ を学びます。
事前確認 — 進む前に次の 3 つができることを確認しましょう。
- コメント の要点を自分の言葉で説明できる
- このレッスンの最小コード (または操作手順) を見ずに書ける
- 練習問題やクイズで間違えた箇所を読み直して理解した
理解度チェック (30 秒)
Q. コメント とは何か、1 文で説明してください。
A. 本文の「このレッスンで分かること」または冒頭の説明文を見直し、自分の言葉で要約できれば OK。詰まったら本レッスンの最初の H2 セクションを読み返してみましょう。
関連レッスン
要件
- メソッドの直前に Javadoc コメント /** ... */ を入れること
- Javadoc 内で @param と @return タグを使って引数と戻り値を説明すること
- b == 0 のときは 0 を返し、それ以外は a / b の結果を返すこと
入出力例
test-cases.txt
safeDivide(10, 2) → 5
safeDivide(10, 0) → 0
safeDivide(-6, 2) → -3
safeDivide(10, 3) → 3