Javadocを使ってソースコードをドキュメントにする

エンジニアのためのJavadoc再入門講座を読んだ。Javadocいろいろ知らなかったなーってことを再確認。Javadocだけじゃなく、ドキュメンテーションコメントを書くとき(Scaladocとか)でも気をつけた方がいいことが色々あったのでまとめておく。

Javadocタグを使いこなす

ブロックタグとインラインタグがある。ブロックタグは @param のように単体で何らかの概念を表現し、行頭に配置しないといけない。インラインタグは主説明やタグセクション内部で特定の部分をマークアップするために使う。

インラインタグ

@literal

特殊な文字をエスケープする。

{@literal List<String>} のように書くと、<などのエスケープが必要な文字をそのまま書ける。

@code

コードをコードとして整形する。{@code ~~~~ } でサンプルコードが書ける。

@link

他のクラスやメソッドに対してリンクを張る。

{@link クラス#メンバ ラベル}

  • クラスを省略した場合、自分自身のメンバに対するリンクとなる。
  • メンバを省略した場合、指定されたクラスへのリンクとなる。
  • ラベルを省略した場合、クラスやメンバに指定した内容がそのまま利用される。
  • {@link パッケージ} とすればパッケージへのリンクとなる。
  • 対象のクラスがインポート済みであればクラス名でOK。そうでなければパッケージ名を含めた形式で書かなければいけない。
  • メソッドはオーバーロード可能なため、メソッドにリンクを張る場合には引数の型を列挙する必要がある。 現在はオーバーロードされていなくても、将来的にされる可能性があるのであれば引数の型を列挙しておいた方がいい。
  • 例:{@link List#add(Object)}

@linkplain

@link と一緒だけどレンダリング効果が違う。@linkは等幅フォントになるけど@linkplainは普通のフォント。

@value

static final で修飾されたフィールドの値を直接埋め込める。@value に指定可能なものは定数に限定される。

ブロックタグ

@param

引数を書く。

@return

返り値を書く。

@throws

例外を書く。

@see

関連項目を書く。複数書くとカンマ区切りで表示される。

Javadocコメントを書くときに気をつけること

最初の1行に全力を傾ける

最初の句点+スペースまたは改行が入るところまでがJavadocの概要欄に表示されるため。また、概要が被るとわけわかんなくなるのでそれも避けた方がいい。

そういえばScaladocも同じような挙動をしていたなぁ…。

ソースの日本語訳を書かない

ソースを自然言語に訳してJavadocに書くのはDRY原則違反。メソッド名やパラメータ名などに十分気を配れば自然言語に訳す必要はない。Javadocコメントにはそのクラス・メソッドの責務やソースコードが読み取れない背景を書くこと。

契約による設計を意識する

事前条件・事後条件・不変条件を明らかにし、Javadocに記述する。

ソースコードがドキュメント

ソースがドキュメントっていうのは数年前までアリエナイと思っていたけど、最近はむしろそうであるべきだという考えになっている。

契約による設計の話も出てきたけど、ソースコードをドキュメントにするっていうのはJavadocだけじゃなく、ソースコード単体で十分に可読性を確保した上で、Javadocで足りない部分をフォローしていくということ。逆に、Javadocをちゃんとしようと思ったら自然とソースコードも綺麗にせざるを得ないということもわかった。

そういう意味でも、この本はクリーンなコードを目指すJava屋さんは読んでおいた方がいいと思う。