Nullを返す可能性があるとき、Javadocにはなんて書けばよいか

Question

Javaで書いていますが、
メソッドがnullを返す可能性が出てきました。
Javadocにそのことを書いておこうと思うのですが、
どのように記述すれば良いと思われますか?

はじめは @exception タグを使おうかと思いましたが、
そのメソッド内で例外が発生するわけではなく、
戻り値でnullが帰ってきた際に呼び出し元で
nullチェックを行わなかった際に例外が起こると思われるので
この @exception タグは違うと思いました。

どなたか良い方法を教えて下さい。

追記
このメソッドは引数に画像ファイル名を受け取り、
画像ファイル名から画像関連のクラスのインスタンスを生成し、
その参照を返すものなのです。
以前は画像ファイルからの生成に失敗したら、真っ白な矩形の画像を生成し、
とりあえずその画像のインスタンスを返すというようにしていました。
ですが、生成に失敗したことを呼び出し元に伝える必要があると考えたため、
nullを返す可能性があるメソッドにしました。
(呼び出し元でnullを確認してもらい、nullが帰ってきたら、
処理に失敗したということなので、そのメソッドを使う人がエラーメッセージを出すなり、
プログラムを終了させるなりなどの対応ができると考えました。)

Answer 1

標準ライブラリーのメソッドで、実際にnullを返す可能性のあるものを参考にされてはいかがでしょうか。

いくつか例を挙げます。

Map.get - Java SE 8 API ドキュメント
http://docs.oracle.com/javase/jp/8/api/java/util/Map.html#get-java.lang.Object-

戻り値: 指定されたキーがマップされている値。このマップにそのキーのマッピングが含まれていない場合はnull

Throwable.getCause - Java SE 8 API ドキュメント
http://docs.oracle.com/javase/jp/8/api/java/lang/Throwable.html#getCause--

戻り値: このスロー可能オブジェクトの原因。原因が存在しないか不明の場合はnull。

File.listFiles - Java SE 8 API ドキュメント
http://docs.oracle.com/javase/jp/8/api/java/io/File.html#listFiles--

戻り値: この抽象パス名が示すディレクトリ内のファイルおよびディレクトリを示す抽象パス名の配列。配列は、ディレクトリが空の場合は空になる。この抽象パス名がディレクトリを示さない場合、または入出力エラーが発生した場合はnullを返す。

Answer 2

標準メソッドで null を返すものを幾つかみてみます。

• Hashmap の get メソッド https://docs.oracle.com/javase/jp/8/api/java/util/HashMap.html#get-java.lang.Object-

...
戻り値:
指定されたキーがマップされている値。このマップにそのキーのマッピングが含まれていない場合はnull
...

• refrect.Method の getAnnotationhttps://docs.oracle.com/javase/jp/8/api/java/lang/reflect/Method.html#getAnnotation-java.lang.Class-

...
戻り値:
存在する場合は、この要素の指定された注釈型の注釈。そうでない場合はnull
...

しかし、自作するメソッドで null を返すのが本当に適切かは再考することをお勧めします。

• 配列を返すメソッドで、返り値としてnullを返す実装はミスを誘発することになります。 https://www.sgnet.co.jp/java/java01_02.html

• Java 8 のOptional を使ってみる http://www.techscore.com/blog/2015/04/28/java-8-optional/

...
Optionalの利用のメリットはその値はないかもしれないということをコードに明示できることです。上の例では、取得したleftやrightはOptionalなので、気をつけずともemptyの場合の処理の記述を強制させられてしまうのです。プログラムの背景や意思を正確に後続の開発者に伝えるという意味でかなり強力です。コメントに「nullかもしれないから気をつけて」と書くよりずっと伝わります
...

scale や swift では optional という仕様を理解しておくことが必須です。
java でも optional が使えるようになっています。

Answer 3

戻り値なら@returnが適切ですね。

/**
 * @return ～ならば{@code null}を返します。
 */

参考: メソッドの戻り値に関するコメント

Comments

[tadanoosakana]

この書き方は初めて知りました。
参考にさせてもらいます。

Answer 4

意図しないnullを出す原因を修正せず、コンパイルも止めたくないなら、
-1とか、""文字などを代入しておくとかでしょうか？

仕様にもよりますが、とりあえず止まりはしないような気がします。