トップ　>　言語共通　>　

Java Python PHP Go Ruby コメントの言語別書式機能比較

Java Python PHP Go Ruby コメントの言語別書式機能比較

Java Python PHP Go Rubyを言語別にコメント書式と機能比較。単行、複数行のコメントとJavadoc PHPDoc Docstring などのサンプルコードを掲載

コメントの言語別書式機能比較 目次

コメントの言語別書式機能比較

コメントには単数行、複数行のコメントがある。

また、ソースコードのコメントに Javadoc などのドキュメント出力用のコメントを含めることで、自動的にリファレンスなどのドキュメントを作成することができる。

ドキュメント出力用のコメントはIDE（VSCodeやPyCharmなど）でマウスを置いた時に説明文や型ヒントがポップアップ表示されるようになる。

コメントの言語別書式機能比較
比較項目 Java PHP Python Go Ruby
単行コメント // // または # # // #
複数行コメント /* */ /* */ なし
便宜的に """ """
(トリプルクォート)		 /* */ =begin
=end
ドキュメント化 /** */
Javadoc		 /** */
PHPDoc		 """ """
Docstring		 //
Go Doc		 # または =begin
RDoc

PHPのコメントは PHPのコメント を参照。
PHPでミニファイをする場合のコメントは ミニファイ（コードの圧縮）を行う場合のコメントは全て /* */ で記述する を参照。

Javaのコメント

Javaのコメントは、//（単行）、/* */（複数行）の2つの書き方がある。この他に /** */ とすることで Javadoc 用のコメントを記述できる。

  1. // は // から改行までをコメントとして認識する。
    単行コメント 記述例
// 単行コメントを書く
  2. /* */ は /* をコメント開始タグ、 */ をコメント終了タグとして認識し、タグの内側をコメントとして認識する。
    複数行コメント 記述例
/* 複数行コメントを書く */

/*
　　  複数行コメントを書く
*/

/*
 *　　複数行コメントを書く
 */

他言語のコメント書式は コメントの言語別書式機能比較 を参照。

Javadocのコメント

/** */ は Javadoc（ジャバドック） と呼ばれ、メソッドの引数や戻り値の意味を記述するために使う。

これを書くことで、HTML形式のAPIドキュメントを生成したり、開発ツール（EclipseやVSCodeなど）上でマウスを置いた時に説明文がポップアップ表示されるようになる。

基本コマンド
コマンドプロンプトやターミナルで、ソースファイルがあるディレクトリに移動して実行する。

-d doc：生成されたHTML群を doc というディレクトリに出力する指定（ディレクトリ名は自由に変更可能）。

[ソースファイル名.java]：対象となるJavaファイルを指定する。*.java とすればカレントディレクトリ内の全ファイルを対象にできる。

javadoc -d doc [ソースファイル名.java]

オプション
パッケージ単位で出力指定する。

-sourcepath でソースのルート（srcなど）を指定し、-subpackages で対象のパッケージ名を指定する。

javadoc -d doc -sourcepath src -subpackages com.example

エンコーディングの指定（文字化け対策）
ソースが UTF-8 で書かれている場合、これを指定しないと文字化けすることがある。

javadoc -d doc -encoding UTF-8 -charset UTF-8 [ファイル名]

Javadoc のタグ

【主要なブロックタグ】
@param：メソッドの引数の説明。
@return：メソッドの戻り値の説明。
@throws / @exception：メソッドが投げる可能性のある例外の説明。
@see：関連する他のクラスやメソッド、URLへのリンク。
@since：機能を導入したバージョン、または機能を導入したJDKのバージョン。
@deprecated：非推奨であることを示す。@Deprecated アノテーションと対にするとメンテナンスしやすい。
@author：クラスやインターフェースの作成者。
@version：ソフトウェアのバージョン。

【特殊な用途のブロックタグ】
{@snippet}：コード例を構文ハイライト付きで記述する。
@highlight：@snippet タグの中で特定の文字列を強調（ハイライト）するサブタグ。
@serial / @serialData：直列化（Serialization）に関する説明。

【インラインタグ】
{@link}：説明文の中に埋め込めるインラインリンク。 
{@linkplain}：リンク部分をコードフォントではなく通常のテキストフォントで表示する
{@inheritDoc}：親クラスやインターフェースのJavadoc説明文をそのままコピーしてくる
{@code}：説明文の中で if や null などのコード断片を等幅フォントで表示する。HTMLエスケープが不要になる。
{@literal}：フォントを変えずに特殊記号（< や >）をそのまま表示したいときに使う。
{@summary}：メソッドの最初の1文（概要）を明示的に指定する。
{@value}：定数（static final）の実際の値をドキュメントに表示する。
{@index}：指定したキーワードを Javadoc 内の検索窓（インデックス）に登録する。

@param

メソッドの引数の説明を記述するタグ。
書式：@param 変数名 変数の説明

@param タグ記述例

@param userid ユーザーID
@param password パスワード
public boolean loginCheck(String userid, String password) {
}

@return

メソッドの戻り値の説明を記述するタグ。
書式：@return 戻り値の説明

@return タグ記述例

@return 認証成功は true、認証失敗は false
public boolean loginCheck(String userid, String password) {
	if ( 処理 ) {
		return true;
	} else {
		return false;
	}
}

@throws

メソッドが投げる可能性のある例外の説明を記述するタグ。
書式：@throws Exceptionクラス名 例外の説明

@throws タグ記述例

@throws Exception 認証エラーまたはシステム例外時にスロー。
public boolean loginCheck(String userid, String password) throws Exception {
}

@exception

メソッドが投げる可能性のある例外の説明を記述するタグ（@throws と同じ意味。開発現場では特別な理由がない場合は、一般的に@throwsを使用する）。
書式：@exception Exceptionクラス名 例外の説明

@exception タグ記述例

@exception IllegalArgumentException 引数が null の不届き者は throws IllegalArgumentException する。
if (userid == null || password == null) {
	throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
}

@see

関連するクラスやメソッドへのリンクを生成するタグ。公式リファレンスなどの外部サイトのURLを直接記述することもできる。
書式：@see パッケージ名.クラス名#メソッド名またはメンバー名（# は対象のクラスのメソッドまたはメンバーを示す）

@see タグ記述例
クラスの指定方法：クラス名 で指定する。

@see UserData

同一クラス内メソッド名の指定方法：#メソッド名（引数の型, ...） で指定する。

@see #validationCheck(UserData)
別クラスのメソッドの指定方法：クラス名#メソッド名（引数の型, ...） で指定する。

@see LoginEvent#loginCheck(Connection, Statement, UserData)

別パッケージのクラスのメソッドの指定方法：パッケージ名.クラス名#メソッド名（引数の型, ...） で指定する。

@see java.util.Collections#sort(java.util.List)

@since

機能を導入したバージョン、または機能を導入したJDKのバージョンを記述するタグ。
書式：@since 機能を導入したバージョンまたは機能を導入したJDKのバージョン

@since タグ記述例

@since JDK25.0.1

@deprecated

非推奨であることを記述するタグ。@Deprecated（アノテーション）と対にして記述することで、ソースコードとドキュメントの両方で非推奨であることを明示でき、メンテナンスしやすい。

書式：@deprecated 説明

@deprecated タグ記述例

@deprecated loginメソッドは {@link #loginCheck(String, String)} メソッドに移行したので非推奨。

@Deprecated
public boolean login(String userid, String password) {
}

@author

クラスやインターフェースの作成者を記述するタグ。
書式：@author 作成者

@author タグ記述例

@author 株式会社ほげほげ ピ世ピ世

@version

ソフトウェアのバージョンを記述するタグ。
書式：@version ソフトウェアのバージョン

@version タグ記述例

@version 1.00

{@snippet}

コード例を記述するタグ。@highlight タグ併用する事で構文ハイライト付きで表示できる。

1. インラインでのコード記述書式：{@snippet : コード }

2. 外部ファイルの region で指定されている範囲を読み込む書式：
{@snippet file="ファイル名" region="ファイル名 の @start region=リージョン名～@end region=リージョン名"}
外部ファイル側の書式：region は @start region=リージョン名 コード @end region=リージョン名

3. @highlight タグ併用の書式：{@snippet タグ内で @highlight substring="ハイライトしたいコードや文字列"

1. {@snippet} インラインでのコード記述例
{@snippet} タグをインラインで使用する場合、{@snippet : 内容} の書式で記述する。
インラインでは必ず、@snippet :（コロン） で記述する必要があるので注意する。
なお、:（コロン） を必要とするタグは、{@snippet} のみである。

/**
 * {@snippet} インラインでのコード記述例：
 * {@snippet :
 *	if (10 < count) { // HTMLエスケープが不要。特殊文字 < や > もそのまま記述可能
 *	}
 * }
 */

2. @snippet タグの外部ファイル参照例
{@snippet file="ファイル名" region="ファイル名 の @start region=リージョン名～@end region=リージョン名"} で、外部ファイルの region で指定されている範囲を読み込むことができる。

外部ファイル側の region は @start region=リージョン名 と @end region=リージョン名 でコードを挟む書式で指定する。

@snippet の参照側の記述例
※ {@snippet file="ファイル名" region="ファイル名 の @start region=リージョン名～@end region=リージョン名"} で指定した側。

{@snippet file="LoginAuthBusiness.java" region="check_null"}

@snippet で参照された外部ファイル側の記述例

public class LoginAuthBusiness {
	// @start region=check_null
	if (userid == null || password == null) {
		throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
	}
	// @end region=check_null
}

3. @snippet タグの @highlight 属性の記述例
@snippet タグ内で、@highlight substring="ハイライトしたいコードや文字列" の書式で指定する。

/**
 * @highlight で特定のキーワードを強調する例：
 * {@snippet :
 *	if (10 < count) { // @highlight substring="count"
 *	}
 * }
 */

/**
 * @highlight で特定のキーワードを強調する例：
 * {@snippet :
 *	throw new Exception("ログイン失敗。残り試行回数n回"); // @highlight substring="ログイン失敗"
 * }
 */

@snippet タグの @replace 属性の使用例
@snippet タグ内で、@replace substring="置換したいコードや文字列" replacement="置換後の文字列" の書式で指定する。

/**
 * コードの一部を置換して表示する例（秘匿情報の伏せ字など）：
 * {@snippet :
 *	String password = "pwhogebono4649"; // @replace substring='"pwhogebono4649"' replacement='"運用で使用するパスワード"'
 * }
 */

{@link}

{@link} タグ記述例
{@link パッケージ名.クラス名#メソッド名またはメンバー名 表示テキスト} の書式で記述する。
# は対象のクラスのメソッドまたはメンバーを示す。
表示テキストは省略可能。省略した場合、指定したリンク先がそのまま表示される。

リンク先には、クラス名、メソッド名、フィールド名などを指定できる。

ブラウザでの表示は、リンク先が コードフォント（等幅フォント）で表示される。通常のテキストフォントで表示したい場合は {@linkplain} タグを使用する。

別パッケージのクラスの記述例

{@link java.util.List} インターフェースを使用。

同一パッケージのクラスの記述例

詳細は {@link LoginEvent} を参照。

同一クラスのメソッドの記述例

バリデーションチェックは {@link #validationCheck(UserData)} で行う。

表示テキスト（ラベル）を変更する記述例

{@link #loginCheck 認証処理} を実行する。

{@inheritDoc}

{@inheritDoc} タグ記述例
親の説明をそのまま継承する記述例

{@inheritDoc}

親の説明に補足を追加する記述例

{@inheritDoc} この実装では、認証失敗時にロックをかける機能が含まれます。

{@code}

{@code} タグ記述例
ブラウザでの表示は、リンク先が コードフォント（等幅フォント）で表示される。通常のテキストフォントで表示したい場合は {@literal} タグを使用する。

※ { や } を含む場合はエスケープが必要になる場合がある。

メソッド名や変数名を強調する記述例

この処理では {@code loginCheck()} メソッドを呼び出す。

比較演算子などをそのまま記述する記述例

条件式 {@code if (10 < count) } を判定に使用する。

複数行にわたるコードを記述する記述例（preタグとの併用）

/**
 * <pre>
 * {@code
 *	if (userid == null || password == null) {
 *		throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
 *	}
 * }
 * </pre>
 */

{@literal}

{@literal} タグ記述例
比較演算子などをそのまま記述する記述例

条件式 {@literal if (10 < count) } を判定に使用する。

ジェネリクスの型表記をそのまま記述する記述例

戻り値は {@literal List<String>} 型で返される。

HTMLタグをそのまま見せる記述例

この値には {@literal <html>} タグを含めることができる。

{@summary}

{@summary} タグ記述例
Javadocの概要（一覧表に表示される短い説明文）の範囲を明示的に指定する。
通常は最初の 句点（。）、ピリオド（.）までが概要として扱われるが、句点・ピリオドの前に説明を区切りたい場合や、文章の途中に句点・ピリオドを含めたい場合、複数の文章を概要に含めたい場合に使用する。

文章の途中にピリオドが含まれる記述例

{@summary ver1.0.0 の認証仕様に基づいたチェック処理を行う。}

文章中に句点が含まれ、複数行にわたる概要を指定する記述例

{@summary
ver1.0.0 の認証仕様に基づいたチェック処理を行う。
認証に3回失敗した場合、始末書の提出を求める。
}

{@value}

{@value} タグ記述例
他クラスのフィールドを指定する場合は {@value クラス名#フィールド名} の書式で記述する。

自身の定数値を表示する記述例

ログイン認証は {@value} 回失敗するとロックされます。
private static final int MAX_ATTEMPTS = 3;

他のクラスの定数値を参照して表示する記述例

デフォルトのポート番号（{@value CommonConfig#DEFAULT_PORT}）を使用する。

{@index}

{@index} タグ記述例
{@index キーワード [説明]} の書式で記述する。
Javadoc右上の検索ボックス（Search）でキーワードを検索できるようになる。

専門用語を検索対象にする記述例
Javadoc右上の検索ボックスで「二段階認証」で検索すると、twoFactorAuth() メソッドが候補に表示されるようになる。

/**
 * {@index 二段階認証} を行う。
 */
public boolean twoFactorAuth() {
}

キーワード [説明] を付けて登録する記述例
Javadoc右上の検索ボックスで「OAuth2.0」で検索すると、loginOAuth2() メソッドが候補に表示されるようになる。説明として「認可プロトコル」が表示される。

/**
 * {@index OAuth2.0 認可プロトコル} を利用したログイン処理を行う。
 */
public boolean loginOAuth2() {
}

他言語のコメント書式は コメントの言語別書式機能比較（Javadoc、PHPDoc、Docstring、Go Doc、RDoc など） を参照。

以下のコードは、実際のソースコードでのJavadocのコメントの事例である。

import java.util.HashMap;
import java.util.Map;

/**
 * <pre>
 * ユーザー認証を管理するクラス。
 * ログインチェックに使用する。
 * 
 * ＜ビジネスクラス共通説明＞
 * データベースアクセスに関する全ての処理を実装できる。
 * エラー処理：例外処理が発生した場合は、上位層へthrows Exceptionする。
 * 呼出元クラスによるエラー時の自動ロールバックを実行する。
 * 
 * ＜このクラス固有の説明＞
 * 引数で受け取ったユーザーIDをキーに、ユーザー管理テーブルからユーザー情報を取得する。
 * ユーザー情報が存在した場合、パスワードが一致するかチェックし、一致した場合、{@link UserData}クラスにユーザー情報を設定する。
 * ユーザー情報が存在しなかった場合、エラーを返す。
 * ログインに3回失敗した場合、始末書を提出するまで二度とシステムを利用できないよう利用制限する。
 * </pre>
 * 
 * @see       LoginEvent#loginCheck(Connection, Statement, UserData)
 * @see       #validationCheck(UserData)
 * @see       UserData
 * @version   1.00
 * @since     JDK25.0.1
 * @author    ピ世ピ世
 */
public class LoginAuthBusiness {

	/** ユーザーごとの失敗回数を記録するマップ */
	private Map<String, Integer> mapFailureCounts = new HashMap<>();

	/** 利用制限がかかる閾値 */
	private static final int MAX_ATTEMPTS = 3;

	/**
	 * 指定されたユーザーID、パスワードでログイン認証を試行する。
	 * 例外処理が発生した場合は、上位層へthrows Exceptionする。
	 * 
	 * @param userid ユーザーID
	 * @param password パスワード
	 * @return 認証成功は true、認証失敗は false
	 * @throws IllegalArgumentException 引数が null の不届き者は throws IllegalArgumentException する。
	 * @throws LoginSuspendedException 3回失敗して「断罪（利用停止）」された場合にスロー。解除には始末書の提出が必要。
	 * @throws Exception 認証エラーまたはシステム例外時にスロー。
	 */
	public boolean loginCheck(String userid, String password) throws LoginSuspendedException, Exception {
		// 引数チェック
		if (userid == null || password == null) {
			throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
		}

		/*
		   既に制限されているかチェック
		   ログインに3回失敗した場合、始末書を提出するまで二度とシステムを利用できないよう利用制限する。
		*/

		/** Javadocコメントの間違った使用例：これはローカル変数なのでJavaDoc対象外（普通のコメント扱い） */
		int currentFailures = mapFailureCounts.getOrDefault(userid, 0);
		if (currentFailures >= MAX_ATTEMPTS) {
			throw new LoginSuspendedException("【利用制限中】貴殿は既に3回失敗し、断罪されました。始末書を提出してください。");
		}

		// 認証処理（シミュレーション）
		if ("admin".equals(userid) && "pass123".equals(password)) {
			mapFailureCounts.remove(userid);
			return true;
		} else {
			currentFailures++;
			mapFailureCounts.put(userid, currentFailures);

			if (currentFailures >= MAX_ATTEMPTS) {
				throw new LoginSuspendedException("失敗回数が " + MAX_ATTEMPTS + " 回に達しました。断罪（利用停止）を実行します。");
			}
			throw new Exception("ログイン失敗。残り試行回数: " + (MAX_ATTEMPTS - currentFailures));
		}
	}
}

PHPのコメント

PHPのコメントは、//（単行）、#（単行）、/* */（複数行）の3つの書き方がある。
一般的には //（単行）、/* */（複数行）の2つを使用する。

この他に /** */ とすることで PHPDoc 用のコメントを記述できる。

  1. // は // から改行までをコメントとして認識する。
    単行コメント 記述例
// 単行コメントを書く
  2. # は // と同様。
  3. /* */ は /* をコメント開始タグ、 */ をコメント終了タグとして認識し、タグの内側をコメントとして認識する。
    複数行コメント 記述例
/* 複数行コメントを書く */

/*
　　  複数行コメントを書く
*/

/*
 *　　複数行コメントを書く
 */

他言語のコメント書式は コメントの言語別書式機能比較 を参照。

PHPDocのコメント

/** */ は PHPDoc（ピーエイチピードック） と呼ばれ、メソッドの引数や戻り値の型、意味を記述するために使う。

これを書くことで、HTML形式のAPIドキュメントを生成したり、開発ツール（VSCodeやPhpStormなど）上でマウスを置いた時に型情報や説明文がポップアップ表示されるようになる。

基本コマンド
phpDocumentor（PHAR形式など）をインストールし、コマンドプロンプトやターミナルで、ソースファイルがあるディレクトリに移動して実行する。

-d [ディレクトリ名]: 対象となるPHPファイルがあるディレクトリを指定する（. はカレントディレクトリ）。

-t [出力先]: 生成されたHTML群を doc というディレクトリに出力する指定（ディレクトリ名は自由に変更可能）。

phpdoc -d . -t doc

オプション
特定のディレクトリやファイルを除外したり、タイトルを指定したりできる。

--ignore で除外するディレクトリやファイルを指定し、-f で特定のファイルを指定する。--title でドキュメントのタイトルを指定する。

phpdoc -d src -t docs --ignore "common/" --title "My PHP Project"

設定ファイル（推奨）
コマンドライン引数が長くなる場合、phpdoc.dist.xml という設定ファイルを用意することで、コマンド引数を省略して実行できる。

ミニファイ（コードの圧縮）を行う場合のコメントは全て /* */ で記述する

HTMLのミニファイ（コードの圧縮）はファイルサイズを小さくして読み込み速度を向上させる目的の他に、HTMLを読みにくくし無断複製を防ぐ目的でも行われる。

ミニファイを行うファイルにPHPのソースコードがあると改行コードが取り除かれてしまい、//、# でコメントを記述すると正しく機能しなくなる。

ミニファイを行う場合は、コメントは全て /* */ で記述する必要がある。

Pythonのコメント

Pythonのコメントは、#（単行） のみである。Java、PHP、Go のような /* */（複数行）のコメントはない。

複数行のコメントがないのは非常に不便なので、便宜的に複数行文字列で使用する """ """ (トリプルクォート) を、複数行のコメントに使用している。

※ 注記 """ を使うときは、前後のプログラムと行頭のスペース（インデント）を合わせる必要がある。ズレているとエラーになる。

  1. """ """ (トリプルクォート) は 1つ目の """ をコメント開始タグ、 2つ目の """ をコメント終了タグとして認識し、タグの内側をコメントとして認識する。
    単行記述 例
""" コメントを書く """

複数行記述 例
"""
　　コメントを書く
　　hogehoge
　　bonobono
　　shimarisu
"""

  2. # は # から改行までをコメントとして認識する。
    記述 例
# コメントを書く
呪術師の解呪

Google Colab や多くのエディタでは、範囲を選択して Ctrl + /（Macは Cmd + /）を押すと、一気に # を付けたり消したりできる。このノロマが・・・って思われたくなかったら使え！

他言語のコメント書式は コメントの言語別書式機能比較 を参照。

Python Docstringのコメント

""" """ は Docstring（ドックストリング） と呼ばれ、関数やクラスの説明、引数の型、戻り値などの説明を記述するために使う。

これを書くことで、HTML形式のAPIドキュメントを生成したり、開発ツール（VSCodeやPyCharmなど）上でマウスを置いた時に説明文や型ヒントがポップアップ表示されるようになる。

書式
Docstringには、Googleスタイル、NumPyスタイル、reStructuredText（標準）などの書き方がある。

用途に合わせてプロジェクト内で統一して記述するのが一般的。

def hoge_func(arg1: int) -> bool:
    """関数の説明。

    Args:
        arg1 (int): 引数の説明
    Returns:
        bool: 戻り値の説明
    """
    return True

基本コマンド (pydoc)
Python標準の pydoc を使い、ブラウザで確認したりHTMLを出力したりできる。

-p [ポート番号]：ローカルサーバーを起動し、ブラウザでドキュメントを閲覧する。
-w [モジュール名]：指定したモジュールのHTMLファイルをカレントディレクトリに出力する。

python -m pydoc -p 8080
python -m pydoc -w my_script

ドキュメント生成ツール（Sphinx）
Pythonで最も一般的なツール。インストール後、プロジェクトのルートディレクトリで初期設定を行い実行する。

sphinx-quickstart：対話形式で設定ファイル（conf.pyなど）を作成する。
sphinx-build：ソースコードからHTMLドキュメントを生成する。

# 初期設定
sphinx-quickstart docs

# HTML生成（docsディレクトリに出力）
sphinx-build -b html source docs

簡易ツール (pdoc)
設定不要で、コマンド一つで素早くHTMLドキュメントを生成できるツール。

-o [出力先]：生成されたHTML群を出力するディレクトリを指定する。

# インストール
pip install pdoc

# カレントディレクトリの全モジュールを対象に生成
pdoc -o ./docs .
# ディレクトリ my_package の全モジュールを対象に生成
pdoc -o ./docs my_package/

他言語のコメント書式は コメントの言語別書式機能比較 を参照。

おすすめ記事

10日で使えるPHP | 未経験のサルでも分かるPHPの学習サイト 10日で使えるPHP | 未経験のサルでも分かるPHPの学習サイト

文系未経験、サルでも10日でPHPを使えるように内容を構成した独学向け学習サイト。不要な基礎はバッサリ切り捨て必要な基礎を十分に深堀した・・・  続きを見る 
Copyright (C) 2001～2026年 e-elder.jp All Rights Reserved.
運営者情報 ご質問はこちらへお願いします info@e-elder.jp