Javaのコメント

プログラムにおけるコメント行は、プログラム１行を書く事と同等な程重要な意味を持ちます。
クラス、定数、プロパティ、コンストラクタ、メソッドの前にjavadoc形式のコメント行を付与することで、
よりプログラムソースの可読性が増します。

一流のプログラムは、目次、章・節立、構成、詳細が優良な書籍を読んだ感覚になります。
端的な話、プログラム言語の記述形式や動作原理が知らない方でも、IPOModelに基づき、
入力情報、主処理(主な目的)、出力情報に展開できれば、プログラムのコメントが明確に記述できます。
そして、プログラムは分からないけどコメントを優良な書籍のように書ければ、設計書に匹敵するぐらいの価値があります。
本章では、Javaのコメント形式について、説明します。

コメントの記述形式

javaのコメントの記述形式は、以下になります。

[課題3]一流のJavaソースで参照した「spring-context」をご確認下さい。
多くのコメント行が「/* */」でもなく「/** */」で表現されています。
たまに、処理の大きな流れの説明に「//」を利用しています。
コメントの記述形式は、「/* */」は利用価値が無いと言っても良いでしょう。

CVS,Subversoin,Gitなどのバージョン管理ツールが無かった頃は、「/* */」に満ち溢れていました。
今は、バージョン管理ツールを導入してバージョンを管理していれば、過去のソース行をコメントにすることは、一切不要です。

• 不要なコメント行は、一切書かない。
• リリースするJavaソースファイルにソースファイルの行を否定したコメントは一切書かない。
• コメントには、「/** */」(javadoc形式)で、明瞭簡潔に機能の目的と入力引数と戻り値を記述する。

Javadoc記述形式

Javadocのコメントの記述形式は、以下になります。

Javadocの記述形式は、「/** コメント内容 */」になります。
Javaのコマンドで説明させて頂きましたjavadocコマンドにより、
Javadocの記述形式で記述したコメントがAPIのhtmlに出力されます。
そのため、HTMLタグ形式の記述が可能です。

Javadocのコメントの記述形式は、次の形式が多いです。

JavaのJavadoc形式、オープンソースや開発現場で多々見られるので１行ごとに「*」を入れて下さい。

Javadocの注意事項とjavadocタグ

Javadoc記述形式及びコメントのポイント

ライセンスの明記

ソースファイル先頭にライセンスを明示します。

HowToWriteJavaより

/**
 * Copyright 2017 yourcompany.
 * 本ソースファイルの著作権は株式会社yourcompanyに所属します。
 * 株式会社yourcompanyの許可なくして、本ソースファイルの
 * 配布、改修、コピー、利用を禁止します。
 * 会社名               ：株式会社yourcompany
 * 組織名               ：システム開発部
 * プロジェクトコード   ：education
 * サブシステムコード   ：samples
 * バージョン           ：1.0
 * 最終更新日時         ：2017/02/10 17:21
 */

//package宣言部

package jp.co.yourcompany.education.samples;

クラスの機能概要

クラス宣言部の前にクラスの主目的を簡潔明瞭に記述します。

@authorタグを付与して作者を明示します。
「@Javadocタグ」を初めて見る方は、Javaの構文である@アノーテションと勘違いし易いです。
Javadocタグは、「/** */」のJavadoc記述形式内に定義されています。
Javadocのwikipediaに利用できるタグが纏められています。

HowToWriteJavaより

/**
 *
 * このクラスは、Javaの全体の構成を分かり易くした
 * 標準出力にメッセージを出力するクラスです。
 *
 * @author Raita.Kuwabara
 */

public class HowToWriteJava {

定数、プロパティ

定数、プロパティにはjavadocコメントを付与します。

	/**
	 * デフォルト値として設定されるメッセージ
	 */

	public static final String MESSAGE_DEFAULT_JA = "こんにちは　日本へ";

	//クラスのプロパティ宣言部

	/**
	 * 出力するメッセージのプロパティです。
	 */

	private String message;

重要メソッドの引数、戻り値

メソッドには、javadocコメントを付与します。
入力引数がある場合には、@paramタグを入力引数分全て定義し、引数全ての説明を記述します。
戻り値がある場合には、@returnタグを定義し、戻り値の説明を記述します。
例外が起こり得る( throws 例外クラス)場合には、@throwsタグを定義し、戻り値の説明を記述します。

@param @return のサンプル

	/**
	 * 外税商品の消費税額を計算する。
	 * @param price 値段(外税)
	 * @parma quntity 数量
	 * @param taxRate 消費税率
	 * @return taxAmount 消費税額(外税)
	 */


	public int calcTaxAmount( int price , int quntity , int taxRate  ){
		return  int(  price  *  ( taxRate  / 100 ) * quntity );
	}

@throwsタグのサンプル
	/**
	 * 指定された商品の在庫数のチェックと商品選択時と現在価格をチェックするサービス
	 * @param 注文リスト 商品別注文のオブジェクトを保持
	 * @throws ServiceException データベースアクセスエラー時、商品が存在しないとき
	 */
	public void itemCheckService(List<Order> orderList) throws ServiceException {

		try{
			例外の起こりうる主処理();
		} ( catch DataAccessException e ) {
			throw new ServiceException( e );
		} ( catch NoItemDataException e ) {
			throw new ServiceException( e );
		}
	}

例外節で詳しく説明しますが、 throw HogeException(厳密には、Throwableを継承した例外クラスです。)が発生する可能性がある場合には、
@throwsタグを利用して例外クラス、どのような例外かを記述します。