プロジェクト

全般

プロフィール

Javaコーディング作法

Java SE 8環境におけるJavaプログラムのコーディング作法メモ。

はじめに

このページに書くコーディング作法は、プログラミング言語JavaとJava Standard Editionの範囲で開発するプログラムを対象としています。対象バージョンは、Java SE 8とします。

プログラムの入出力

コンソール(標準入力・出力)

コンソール出力をきれいに

プログラムの利用者にとって意味不明な文字列でコンソールを汚さないようにします。
デバッグや動作確認で必要なメッセージは、秩序を持って出力します。
System.out.printlnやprintfの安易な使用はコンソールを汚すので、ロギングAPIを使用するかそれに準じる出力を行います。ロギングAPIを使うときも、利用者がメッセージを峻別できるようルールを明確に定義します。例えば、開発者が使うデバッグ用のログは、レベルFINE, FINER, FINESTとする、等です。

ログ出力

ロギングAPIによって出力先の設定、出力書式の設定、出力の抑制を行いながら必要なメッセージをログに出力します。コンソール出力をきれいに保つには必要な機能です。

パッケージ構成

ロギングAPIでは、ロガー名に通常完全修飾名(パッケージ名付きのクラス名)を使います。その場合、パッケージ階層に応じて出力の抑制制御ができるようになります。例えば、次の階層構造でクラスが作られていたとします。

myapp
  +-- view
  |     +-- MainView
  |     +-- ProcessView
  +-- model
        +-- Hello

  • アプリケーション全体のログ出力レベルをCONFIG以上に指定する場合
    myapp.level = CONFIG
    
  • アプリケーション全体のログはWARNING、ただし表示系はFINE以上に指定する場合
    myapp.level = WARNING
    myapp.view.level = FINE
    

    などと指定できます。

GUI

マルチスレッドおよび並列処理

データ構造

メソッド

引数と戻り値とnull

最適化とメソッド

HotSpot VMのJITコンパイラは、繰り返し実行されるメソッドをネイティブにコンパイルします。また、サイズが小さなメソッドはインライン化の対象となります。JITコンパイラで最適化されやすいように、メソッドはシンプルに小さく作成するとよいでしょう。

例外

禁じ手

これをやられると困る、ということを列挙します。

  • JavaVMの終了(System.exitコール)
  • GCの実行(System.gcコール)

Javadocコメント

パッケージおよびクラスの仕様を、その利用者に説明するための文書の1つとして、ソースコードに所定の書式(Javadoc形式)で記載されたコメントからjavadocツールによって生成したものがAPI仕様書(APIリファレンス)になります。

したがって、クラス(型)の利用者から可視であるpublic、protectedな要素にJavadoc形式のコメントを記述していきます。
クラス利用者はソースコード上のコメントを直接参照するのではなく、ソースコード上のコメントからjavadocツールによって生成されたHTMLをWebブラウザ上で参照します。そのため、Javadoc形式のコメントはHTMLで見やすいことを念頭に記述します。

一方、パッケージスコープやprivateの要素は、クラス(型)の利用者ではなく、クラス(型)の開発者に向けたコメントを記述します。それは、API仕様書とは異なる視点で書かれ、またクラス(型)のソースコードと一緒に参照するので、ソースコード上で見やすいことを念頭に記述します。

本節は、API仕様書(APIリファレンス)を生成するためのドキュメントコメントの作法について記載します。

全般

パッケージの仕様を説明するJavadocコメントは、package-info.javaに記述します。
クラス(インタフェース、列挙型)の仕様を説明するJavadocコメントは、各ソースファイルのクラス定義の直前に記述します。

読み手に分かりやすいように、文章の他、箇条書き、使用例、表などを交えて説明するとよいです。

  • 文体は、「だ/である」調
  • 長いコメントの説明文章は最初の一文に要旨をまとめる
  • 変更履歴はコメントにしない(変更管理ツールおよび改訂毎のリリースノート等に書く)

概要説明文

コメントの最初の1文は、概要説明文として、クラス一覧、メソッド一覧、フィールド一覧の概要説明に抽出されます。最初の1文とは、Javadoc形式コメントを開始してから、最初のピリオド"."(日本語であれば句点)までです。

最初の1文には、その要素を端的に説明する一文を記述します。

説明文の段落分け

説明文を複数段落で記述するときは、2つ目以降の段落をそれぞれHTMLタグの段落要素(<p>…</p>)で囲みます。1つ目の段落には不要です。
改行にHTMLタグ<br>を使うのは極力避けます。箇条書きの方法は後述。

説明文章における見た目の修飾

  • 太字(強調文字)は、HTMLタグの<b>...</b>を使う
  • ソースコード上に出てくる用語(予約語、型名、パッケージ名、メソッド名、フィールド名など)は、{@code theName} を使う
    他のクラス・メソッドのJavadocドキュメントへのハイパーリンクを記載する{@link my.Class#member linkname}という記法もある。ただしjavadocツールで一緒に生成するクラス以外を指定した場合は、javadocのコマンドラインオプション-link-linkofflineで、参照したいJavadocのURLを指定する。
  • 大なり・小なり記号などHTMLタグに影響を及ぼす文字を使う場合は、{@literal inValue > outValue} を使う

箇条書き

箇条書きは、HTMLタグの箇条書き要素で記述します。HTMLの箇条書きは、番号なし(<ul>...</ul>)、番号付き(<ol>...</ol>)があります。

ソースコードブロック

複数行のソースコードを記述する場合は、HTMLタグのpreと{@code}を組み合わせて使用します。

<pre>{@code
public class Alfa extends Bravo {
    private Alfa() {}
}
}</pre>

個別

プロジェクト全体のドキュメント

開発・リリース単位において、overview.htmlを作って記述します。
ビルド方法、依存するライブラリ、対象Javaバージョン、ビルド時に生じるコンパイル警告、既知の問題点などを記述します。

また上位レベルの分割(サブシステム、パッケージ分割)などの設計思想を書きます。
パッケージ図、概念モデル図、主要シーケンス図などをUMLツールで作成し、その図を含めてもよいでしょう。

パッケージのドキュメント

パッケージ毎に1つ package-info.java ファイルを作成し、そこにJavadoc形式のコメントで概要説明を記述します。

型(クラス、インタフェース、列挙型)のドキュメント

T.B.D.

フィールドのドキュメント

T.B.D.

メソッドのドキュメント

T.B.D.

注意事項

コメントでは改行していてもJavadoc文書(HTML)では改行されない

改行が必要な単位を段落タグ<p>~</p>で示します。

/**
 * キューに詰まれているアイテム数を取得する。
 * <p>キューに詰まれ、まだ実行状態になっていない待機アイテムの数を計算して返却します。</p>
 *  :
 */
  • Java SE 7 までは<p>タグを単独で使用できましたが、Java SE 8からは<p>タグを単独で使用するとjavadocコマンドで警告となります。

クリップボードから画像を追加 (サイズの上限: 1 GB)