Javadocを書こう #Java

javadocの重要性

コード上にコメントが書いてあると、すぐに何の処理が書いてあるのかわかりますよね
javadocを書いた場合、参照した先でもそのコメントがみられるので
javadocだけでどんな処理のものなのか把握でき、使えるというわけです

逆に、javadocを適当に書くと
そのクラスだったりメソッドが何をしてくれるのか把握できず、いちいちコードを解読しに行かなければならないので
シンプルに効率が悪いわけですね

複数人で開発するのが当たり前な現状、自分でない誰かが
自分の作ったものを使うことが当たり前なわけで
すなわち思いやりの心をもって書きましょうってことですね

どこに書くのか

classとpublicメソッドには必須でしょうね
privateやprotectedはなんだろう、離れた場所で使うことあんまないならいらないのかも？って感じですかね
最終的にわかりやすければおーけーなのでは

つまり何を書けばいいのか

あまり多く書きすぎても逆に見づらいでしょうし
少なかったら処理わかんないしで

何を参考にしましょうかと

公式でしょ

みんな大好きSystem.out.printlnでおなじみ、Systemクラスさんです

System.java

/**
 * The <code>System</code> class contains several useful class fields
 * and methods. It cannot be instantiated.
 *
 * <p>Among the facilities provided by the <code>System</code> class
 * are standard input, standard output, and error output streams;
 * access to externally defined properties and environment
 * variables; a means of loading files and libraries; and a utility
 * method for quickly copying a portion of an array.
 *
 * @author  unascribed
 * @since   JDK1.0
 */
public final class System {

実際の見え方はこう

java.lang.System

Systemクラスには有用なクラス・フィールドおよびメソッドがあります。インスタンス化することはできません。

Systemクラスによって得られる機能には、標準入力、標準出力、およびエラー出力ストリーム、外部的に定義されたプロパティお
よび環境変数へのアクセス、ファイルおよびライブラリのローディング方法、配列の一部をすばやくコピーするユーティリティ・メソッドがあ
ります。
導入されたバージョン:
      JDK1.0

クラス説明なので、

なにをするクラスなのか
インスタンスできない旨を明記
全体的にざっくりどんなメソッドとかがあるのか
導入されたバージョン

を記載していますね

注目したいのは段落分けの<p>タグやコードを記載する際の<code>タグだと思います
しっかりHTMLで書くことによって、たいへん見やすくなりますね
codeタグは{@code null}のようにしてもいいでしょうし、{@linkplain メソッド名表示テキスト}のようにして
参照先に飛べるようにしてもいいですね
<ul>
<li>
</ul>
での箇条書きや、<br>での改行などで、しっかりjavadoc参照されたときを見ながら編集していくと
直書きのjavadocは多少長くなりますけど、参照先での説明がめっちゃ見やすくなりますね!

メソッドはというと

System.java

    /**
     * Reassigns the "standard" output stream.
     *
     * <p>First, if there is a security manager, its <code>checkPermission</code>
     * method is called with a <code>RuntimePermission("setIO")</code> permission
     *  to see if it's ok to reassign the "standard" output stream.
     *
     * @param out the new standard output stream
     *
     * @throws SecurityException
     *        if a security manager exists and its
     *        <code>checkPermission</code> method doesn't allow
     *        reassigning of the standard output stream.
     *
     * @see SecurityManager#checkPermission
     * @see java.lang.RuntimePermission
     *
     * @since   JDK1.1
     */
    public static void setOut(PrintStream out) {
        checkIO();
        setOut0(out);
    }

実際の見え方は

void java.lang.System.setOut(PrintStream out)

setOut
 public static void setOut(PrintStream out)

「標準」出力ストリームを割り当てし直します。 
セキュリティ・マネージャが存在する場合は、標準出力ストリームを割り当てし直してよいかどうかを確認するために、RuntimePermission("setIO")アクセス権を使ってcheckPermissionメソッドが呼び出されます。
パラメータ:
      out - 新しい標準出力ストリーム
例外:
      SecurityException - セキュリティ・マネージャが存在し、そのcheckPermissionメソッドが標準出力ストリームの再割り当てを許可しない場合。
導入されたバージョン:
      JDK1.1
関連項目:
      SecurityManager.checkPermission(java.security.Permission), RuntimePermission

ということで、やはり
@param引数(out アウトとか翻訳しただけでなく、どんな引数が入るのかしっかりと情報を)
@return戻り値(取得結果とかざっくりせずに、何を返してくれるのか具体的かつ簡潔に)
@throws例外(どんな場合に起こるのかを漏れなく簡潔に)
@see参照
@since導入バージョン
などが重要みたいですね
ドキュメントで重要そうに見えるのは

何をするメソッドか
場合によって違う動きをするならその旨
(書いてないけど)引数にnullはいいのか
戻り値にnullがあり得ないとかどうとか

みたいなこと書いてあったらうれしくないですか

だからといって

たいした処理でもないやつに100万行の説明文あっても無駄なように、書きすぎもよくなくて
程よくわかりやすく、シンプルに明確に
めっちゃむずくねそれ...

そもそも命名が正しければおおむね何してくれるのかわかるわけで、その上javadocがあればもう完璧って感じだと思うので
命名とjavadocが重要ですよねやっぱ

ということでjavadocをしっかりと書いていこうと思いました