この文書はJava開発者にとって多くの標準と指針について議論した。この文書はかなり大きいので、利便のためこの章にまとめた。この章を再度印刷して作業場所の壁に貼っていつでも使えるようにすることを推奨する。
この章ではJavaコーディング標準、トピックの集まりを1ページにまとめたものをいくつか用意した。これらのトピックとは、
この文書で述べた標準や指針の残りをまとめる前に、もういちど最優先規範を繰り返しておこう。
優れた開発者はプログラミングの他に開発するべき多くのことがあることを知っている。
偉大な開発者は開発の他に開発するべき多くのことがあることを知っている。
以下に述べる少数の例外はあるが、名前を付けるときはフルスペルの英語記述を常に行う。さらに、通常は小文字を使用し、1つの名前を構成する先頭ではない単語の最初の1文字とクラス名とインタフェース名の最初の1文字は大文字とする。
| 項目 | 命名規約 | 例 |
|---|---|---|
| 引数/パラメータ | 渡される値/オブジェクトはフルスペルの英語記述を使い、名前の接頭辞に'a'や'an'があってもよい。1つのやり方を選んだらそれに合わせることが重要。 | customer、account、あるいはaCustomer、anAccount |
| フィールド/プロパティ | フィールドは先頭1文字が小文字で続く単語の先頭1文字を大文字とするフルスペルの英語記述を使う。 | firstName、lastName、warpSpeed |
| 真偽型の読み出しメソッド(getter) | booleanのgetterは全て'is'を接頭辞とする。この命名標準に従うなら、'is'に続いてフィールド名を継げればよい。 | isPersistent()、isString()、isCharacter() |
| クラス | フルスペルの英語記述で、構成する単語の先頭1文字を大文字とする | Customer、SavingsAccount |
| コンパイル単位ファイル | クラスやインタフェース名、1つ以上のクラスがあるなら主要なクラス名に'.java'を付けソースファイル名とする。 | Customer.java、SavingsAccount.java、Singleton.java |
| コンポーネント/ウィジェット | コンポーネントが何に使われるかをフルスペルの英語記述で表現し、コンポーネントの型をその後に続ける。 | okButton、customerList、fileMenu |
| コンストラクタ | クラス名を使う。 | Customer()、SavingsAccout() |
| デストラクタ | Javaはデストラクタを持っていないが、代わりにメソッドがオブジェクトをガーベッジコレクションされる前に呼ばれる。 | finalize() |
| 例外 | 文字'e'が例外を表すのに一般的に用いられる。 | e |
| final staticフィールド(定数) | 全て大文字で単語間をアンダースコアで結ぶ。final static読み出しメソッド(getter)を使用する方が柔軟性が増すのでよいやり方である。 | MIN_BALANCE、DEFAULT_DATE |
| 項目 | 命名規約 | 例 |
|---|---|---|
| 設定メソッド(getter) | フィールド名に'get'を接頭辞として付ける。 | getFirstName()、getLastName()、getWarpSpeed() |
| インタフェース | インタフェースがカプセル化する概念をフルスペルの英語記述で、構成する単語の最初の1文字を大文字とする。名前の接尾辞に'able'、'ible'や'er'を付ける習慣があるが必須ではない。 | Runnable、Contactable、Prompter、Singleton |
| ローカル変数 | 最初の1文字を小文字とするフルスペルの英語記述で、存在するフィールドを隠蔽しない。例えば、'firstName'というフィールドがあれば、ローカル変数に'firstName'は用いない。 | grandTotal、customer、newAccount |
| ループカウンタ | 文字、、や''が一般的に用いられる。 | i、j、k、counter |
| パッケージ | フルスペルの英語記述だが、すべて小文字とする。グローバルパッケージはインターネットドメインを逆順にしたものをパッケージ名と継げる。 | java.awt、com.ambysoft.www.persistence.mapping |
| メソッド | メソッドが何をするのかをフルスペルの英語記述で、可能な限り先頭を能動態の動詞で始め、最初の1文字は小文字とする。 | openField()、addAccount() |
| 設定メソッド(Setter) | フィールド名に接頭辞'set'を付ける。 | setFirstName()、setLastName()、setWarpSpeed() |
以下の規約には賛成できないけれども、Sunが推奨する型によってローカル変数につける短い名前がある。よりよい規約はフルスペルの英語記述を使うことだ、なまけずに。
| 変数の型 | 推奨する命名規約 |
|---|---|
| offset | off |
| length | len |
| byte | b |
| char | c |
| double | d |
| float | f |
| long | l |
| Object | o |
| String | s |
| 任意の値 | v |
ドキュメントに関してよいルールは、自分自身にもしコードを見たことがないとしたら、それほど時間をかけずに効率的にコードを理解するにはどんな情報を必要とするかを問いかけることである。
以下の表は3種類のJavaコメントと推奨する使い方を述べている。
| コメント種類 | 使用方法 | 例 |
|---|---|---|
| ドキュメント化コメント | ドキュメント化したいinterface, class,メソッド,フィールドの直前に書く。ドキュメント化コメントはjavadocによって処理され、クラスの外部ドキュメントとして生成される。 | /** 顧客（Customer）- 顧客は われわれがサービスまたは 製品を売った人物もしくは 組織のいずれかである。 @author S.W.Ambler */ |
| C風コメント | 特定のコードを無効化したいが、後で使用するかもしれないので残しておくためにコメント化する時や、デバッグ時に一時的に無効化するときに使用(19) | /* このコードはJ.T.Kirkに よって1997.12.9に前述の コードと置き換えたため コメント化した。 2年間不要であるならば、 削除せよ。 ... (ソースコード) */ |
| 単一行コメント | メソッド内にて、ビジネスロジック、コードの概要、一時変数の定義等を記述 | // 1995年2月に開始された // サレク氏の寛大なキャン // ペーンで定められた通り // 1000$を超える請求には、 // 全て5%割引を適用する。 |
以下の表は書いたコードの各部分ごとに何をドキュメントするかをまとめたものである。
| 項目 | ドキュメントすること |
|---|---|
| 引数/パラメータ | パラメータの型、何に使われるか、制約や事前条件、例 |
| フィールド/プロパティ | その説明、適用できる不変表明、例、並行性、可視性の説明 |
| クラス | クラスの目的、既知のバグ、開発/保守の履歴、適用できる不変表明、並行性の戦略 |
| コンパイル単位 | 定義される各クラス/インタフェースと簡単な説明、ファイル名と識別情報、著作権表記 |
| 読み出しメソッド(Getter) | もし遅延生成を使っていればその理由 |
| インタフェース | 目的、どのように使うべきか、使わないべきか |
| ローカル変数 | その使用、目的 |
| メソッド-ドキュメント | メソッドが何をして何故そうするのか、必要とするパラメータ、何を返却するか、既知のバグ、スローする例外、可視性の決定、メソッドがオブジェクトをどう変更するか、コード変更の履歴、正しい起動方法の例、事前条件と事後条件、並行性についての記述 |
| メソッド-内部コメント | 制御構造、コードがする事とその理由、ローカル変数、難しく複雑なコード、処理順序 |
| パッケージ | パッケージの説明、パッケージに含まれるクラス |
Javaコードの保守性と拡張性に欠かせない規約と標準はたくさん存在する。99.9%の時間をあなたの仲間の開発者である人々のためにプログラムすることが、マシンのためにプログラムすることより重要である。他の人にコードを理解しやすくすることこそ最重要である。
| 規約の対象 | 規約 |
|---|---|
| アクセッサ・メソッド | データベースに格納されるフィールドについては遅延生成を考慮せよ すべてのフィールドを獲得したい変更するのにアクセッサを使え 定数についてアクセッサを使え コレクションについては要素を挿入・削除するメソッドを設けよ 可能な限りアクセッサはpublicではなくprotectedにせよ |
| フィールド | フィールドは常にprivateと宣言せよ フィールドを直接アクセスせずにアクセッサ・メソッドを使え 定数にfinal staticフィールドを使わずアクセッサ・メソッドを使え 名前を隠蔽するな 常にstaticフィールドは初期化せよ |
| クラス | publicとprotectedなインタフェースは最小限にせよ コーディングする前にクラスのpublicインタフェースを定義せよ フィールドとメソッドは以下の順で宣言せよ |
| ローカル変数 | 名前を隠蔽するな 一行には1つのローカル変数を宣言せよ 行末コメントでドキュメントせよ 使う直前で宣言せよ ひとつのことだけに使え |
| メソッド | コードをドキュメントせよ 段落分けせよ 制御構造の前に1行の空白とメソッドの宣言の前に2行の空白をいれよ 30秒以内に理解できなくてはならない 簡潔に 一行には1コマンドを書く 可能な限りメソッドの可視性を制約せよ 命令の順序を特定せよ |