戻る

Simple, Open, Share

Home
トップページ 会社案内 Javaコーディング標準 開発系メモ Q&A

5、コメント

(62) javadoc の活用

/** コメント */ を多いに活用すること.
このコメントは,javadocや同様のツールによってHTML形式でのドキュメントに変換することができる.

javaのコメントには,3種類ある.

/** ... */ javadocコメント.html形式でドキュメント出力される.
/* */ 通常のコメント,内部的
// 通常のコメント,内部的 publicクラス,メソッド,フィールドには必ず /** */ コメントを付ける.

(63) 長いコメント

コメントが複数行に渡る場合は,最初の短い一文で何が言いたいかを書き,その後に長い コメントを付けること.

(64) javadocタグ

/** */コメント中,@ から始まるキーワード(javadocタグ)を挙げる.

    @author author-name
    @param paramName description
    @return description of return value
    @exception exceptionName description
    @see string
    @see URL
    @see classname#methodname

param, returnに特別の注意が必要な場合,その旨コメントする.

例えば,引数が出力用であり,変更される場合.

例1:

/**
* 境界ボックスを得る.
*
* @param b境界ボックス(メモリと速度効率のため,出力引数)
*/
void getBBox(BBox b) { b.min = this.min; b.max = this.max; }

(65) クラスコメント

/** */ コメントは,機能概要,すなわち外部的な仕様の記述に用い,クラスおよびメソッドの定義が始まる直前に書く.
このコメントの第1行は,特別な扱いを持つ.
すなわち,htmlのMethod Indexに使用される.
よって,最初の1行は,コメント対象の外部的な機能の短い説明となる.
その行は,半角ピリオド(.),もしくはHTMLタグで終る.この1行目に続けて,機能を説明する.

例:
/** * スタックを表現するクラス.
* スタックは先入れ後だしのデータ構造.
*
* 要素数は,countに保存し,要素は,Vectorに入れる.
*
* @see util.Vector
* @author yourNameHere
*/

public class Stack {
/**
* 現在の要素数.
* 非負の数であり,capacity以下である.
*/

protected int count;

/**
* 一番上の要素を取り出す.
* 要素数は1つ減る.
*
* 使用例:
* Stack s = new Stack(10);
* s.push(99);
* int i = pop(); // iは99のはず

* @return 上の要素
*/

public int pop() { ... }
}

コメント中に,使用例など書く場合,

(66) // vs. /* */

メソッドやクラスの内部的なコメントは,/* */ か,// を使用する.長さで判断してよい.
1行コメントは,// を使った方がよい.

例1:

    /*
    * 戦略:
    * 1. まずnodeを探す
    * 2. cloneする
    * 3. inserterにcloneを追加要請
    * 4. 成功したら,nodeを削除
    */

例2:
    int index = -1; // -1はinvalidな値を意味する

参考: この方がさらによい.

    static final int INVALID= -1;
    int index = INVALID;

(67) Design by Contract(契約による設計)

契約による設計を行うため,プロジェクトにAssertクラスを用意せよ.
Assertクラスを使って,契約を表現せよ.

例:

class Stack {
    private int capacity;
    private int itemCount;
    public void push(Object o) {
        Assert.require(o != null); // 事前条件
        // ...
        // ...
        Assert.ensure(this.contains(o)); // 事後条件
    }

    public boolean invariant() { // 不変条件
        Assert.invariant(0 <= capacity);
        Assert.invariant(0 <= itemCount);
        Assert.invariant(itemCount <= capacity);
        return true;
    }
}

注意: ユーザ入力チェックなどをassertしてはいけない.
バグを捕まえるためにassertせよ.

補足: J2SE1.4以降では,assertキーワードを利用せよ.

©2014 Powered by 株式会社開成