コメントを書く

3 か月後の自分は、書いた理由を必ず忘れている

動くコードには、なぜその式にしたのかが残りません。半年後に読み返して「ここ、何をしていたんだっけ」となるのは、他人のコードだけではなく自分のコードでも同じです。そこで使うのがコメントです。コンパイラはコメントを読み飛ばすので、何を書いても動きは変わりません。

書き方は 2 つあります。// はそこから行末まで、/* から */ までは何行でもコメントになります。

/* を書いて */ を書き忘れると、そこから下のコード全部がコメント扱いになり、まったく関係ない場所で大量のエラーが出ます。閉じ記号は先に打ってから中身を書くと安全です。

コメントの中身は「何をしているか」ではなく「なぜそうしたか」を書きます。i++; // i を 1 増やす はコードを読めば分かることの繰り返しですが、i++; // 次のページに進める なら意図が残ります。

/** で書くと、IDE のホバーに出る

/** で始めるコメントだけは特別扱いで、Javadoc と呼ばれます。クラスやメソッドの直前に置くと、javadoc コマンドがドキュメントを生成し、エディタでもメソッド名にカーソルを合わせたときに説明として表示されます。

@param で引数を、@return で戻り値を説明します。

@param は引数の数だけ並べ、名前はメソッドの引数名と揃えます。/* (アスタリスク 1 つ) で書くとただのブロックコメントになり、ホバーにも生成物にも出てきません。差は最初の * 1 文字だけです。

0 で割ると、その場でプログラムが止まる

今回の課題は、割り算をするメソッドに Javadoc を付ける形です。ここで 1 つだけ、割り算そのものの注意があります。

Java の整数の割り算は、割る数が 0 だと例外を投げてプログラムを落とします。返す値が変になるのではなく、そこで停止します。防ぎ方は単純で、割る前に if で割る数を確かめ、0 のときは割り算をせずに決めておいた値を返します。

なお int どうしの割り算は小数を切り捨てます。10 / 3 は 3.33... ではなく 3 です。

やってみよう

safeDivide(int a, int b) を完成させてください。やることは次の 2 つです。

1. b が 0 のときは割り算をせず 0 を返し、それ以外は a / b の結果を返す
2. メソッドの直前に /** ... */ を置き、@param を 2 本と @return を 1 本書く

Javadoc の文章は自由です。a が何で b が何か、0 を渡したときにどうなるかを、自分の言葉で書いてください。半年後の自分が最初に読む 3 行になります。

1. メソッドの直前に Javadoc コメント /** ... */ を入れること
2. Javadoc 内で @param と @return タグを使って引数と戻り値を説明すること
3. b == 0 のときは 0 を返し、それ以外は a / b の結果を返すこと