Okapi Project

コメントに関する規約

バージョン
2003 年 12 月 25 日 Ver.1.0
作成者
T.Itoh ( Xware )

要約

ソースの可読性を向上させるのはソースのスタイルを統一することばかりではありません。ソースの中にわかりやすいコメントを記述することも可読性の向上に大きくつながります。ここでは JavaDoc 用のコメントを利用することを前提として実際にどのようなコメントをつけていけば適切なのかを詳細に解説していきます。

目次


5.コメントに関する規約

コメントについては基本的には JavaDoc を出力することを考慮して JavaDoc コメントに準拠することを前提とします。以下に詳細なコメントに関する規約をまとめます。

5.1.ヘッダ部のコメント

ヘッダ部に記述するコメントは以下の例のようにタイトル、説明、著作権(Copyright)、作成会社名、変更履歴を記述します。このコメントは JavaDoc へ反映することはしないこととしますので、/* … */ の形式で記述します。また、ヘッダ部のコメントはすべての Java ソースファイルに記述しなくてはなりません。
/*
 * タイトル:コーディング規約用のサンプル処理
 * 説明    :PostgreSQL の起動と停止を行う
 *
 * 著作権  :Copyright(c) 2003 XWARE
 * 会社名  :エクスウェア株式会社
 *
 * 変更履歴:2003.10.31 Friday
 *        :新規登録
 *        :2003.11.01 Saturday
 *        :レビュー後の修正を反映
 *
 */

5.2.クラス(インターフェース)コメント

クラスコメントは機能概要・外部的な仕様の記述に用いるコメントで、クラス宣言の直前に記述します。クラスコメントでは JavaDoc タグのうち、@author, @version を必ず記述するものとします。
/**
 * コーディング規約用のサンプル処理です。
 *
 * @author T.Itoh(titoh@xware.co.jp)
 * @version 1.0
 *
 */
public class SampleProcess {

5.3.メソッドコメント

メソッドコメントは、クラスコメントと同様にそのメソッドの機能概要を記述し、パラメータ(@param)・戻り値(@return)・関連クラス名(@see)について記述します。
/**
 * コーディング規約用のサンプルメソッドです。引数を処理して戻り値を返却します。
 *
 * @param 処理番号 number(int), 行データ lineData(String)
 * @return 処理結果データ
 * @see java.util.StringTokenizer
 *
 */
public String sampleMethod(int number, String lineData){


Copyright © 2003 - 2006 Okapi Project All Rights Reserved.