PHPでプログラムを書く際、コードに説明を残すためのコメント機能は欠かせません。コメントを適切に記述することによって、後から見返したときにコードの意図を理解しやすくなり、チーム開発においても他のメンバーがコードを把握しやすくなります。
しかし、PHPには複数のコメント記法があり、どの方法が最適なのか、それぞれどのような違いがあるのか、初心者の方は迷うこともあるでしょう。また、関数やクラスに対するコメントの書き方についても、正しい方法を知っておく必要があります。
この記事では、「PHPでコメントを書く3つの方法」と「関数やクラスに対するDocCommentの書き方」について、実際に使えるサンプルコードと共に詳しく解説していきます。
PHPでコメントを書く3つの方法
PHPでコメントを書く際は、コードの実行に影響を与えず説明文を残すことができます。コメントの書き方は3つあり、それぞれ用途に応じて使い分けることが重要です。
- //で1行コメントを書く
- /* */で複数行コメントを書く
- #でシェルスクリプト形式のコメントを書く
それぞれの方法は記述形式が異なり、適用される範囲や使用場面にも違いがあります。1行コメントは短い説明に適しており、複数行コメントは長文の説明やコードブロックの無効化に便利で、シェルスクリプト形式はCLIスクリプトで活用されることが多いです。
それでは各項目について、詳しく解説していきます。
//で1行コメントを書く
//による1行コメントは、PHPで最も頻繁に使用されるコメント記法です。//を記述した位置から行末までがコメントとして扱われ、プログラムの実行には影響を与えません。
<?php
// これは1行コメントです
$name = "Tanaka"; // 変数に名前を代入
// 計算処理
$price = 1000;
$tax = 0.1;
$total = $price * (1 + $tax); // 税込価格を計算
?>
上記のコードでは、//の後ろに記述された文字列がコメントとして処理されています。変数の宣言や計算処理の横に簡潔な説明を添えることで、コードの可読性を高めることができます。
//によるコメントは行末で自動的に終了するため、閉じタグを記述する必要がありません。短い説明や一時的なメモを残す際に適しており、コードの各行に対する補足説明として活用されます。
【PR】プログラミングや生成AIを無料で学べる「コードキャンプフリー」
/* */で複数行コメントを書く
/* */によるコメントは、複数行にわたる長い説明を記述する際に使用される記法です。/*でコメントを開始し、*/でコメントを終了することで、その間に記述された全ての内容がコメントとして扱われます。
<?php
/*
このプログラムは商品の価格計算を行います。
税率は10%で計算され、
最終的な税込価格を表示します。
*/
$price = 1000;
$tax = 0.1;
$total = $price * (1 + $tax);
/* 以下のコードは一時的に無効化
$discount = 0.2;
$total = $total * (1 - $discount);
*/
?>
上記のコードでは、プログラムの概要を複数行にわたって説明し、さらに特定のコードブロックを一時的に無効化しています。/* */によるコメントは、開始記号と終了記号で囲まれた範囲全体がコメントになるため、長文の説明やデバッグ時のコード無効化に便利です。
複数行コメントを使用する際は、/* */を入れ子にすることができない点に注意が必要です。コメント内に*/が含まれていると、そこでコメントが終了してしまい、意図しない動作を引き起こす可能性があります。
#でシェルスクリプト形式のコメントを書く
#によるコメントは、シェルスクリプトと同じ形式でコメントを記述する方法です。#を記述した位置から行末までがコメントとして扱われ、//と同じ動作をします。
<?php
# これはシェルスクリプト形式のコメントです
$name = "Suzuki"; # 変数に名前を代入
# CLIスクリプトで使用されることが多い
$result = $name . "さん";
echo $result; # 結果を出力
?>
上記のコードでは、#の後ろに記述された文字列がコメントとして処理されています。#によるコメントは、//と機能的には全く同じで、記述方法が異なるだけです。
#形式のコメントは、PHPをコマンドラインから実行するCLIスクリプトで使用されることが多く、シェルスクリプトとの親和性が高い特徴があります。ただし、一般的なWeb開発において、//による1行コメントが広く使用されており、チーム開発では統一された記法を採用することが推奨されます。
PHPのDocCommentで関数やクラスにコメントを書く方法
PHPのDocCommentは関数やクラス、メソッドに対して、構造化されたコメントを記述するための特別な記法です。以下のような@から始まるタグを使用することで、引数や戻り値などの詳細情報を明示的に記録できます。
- @paramタグで引数を説明する
- @returnタグで戻り値を説明する
それぞれのタグは明確な役割を持っており、関数の仕様を文書化する際に、統一された形式で情報を記述できます。DocCommentを適切に記述することで、IDEによる入力補完やコードドキュメントの自動生成が可能になり、開発効率が向上します。
それでは各項目について、詳しく解説していきます。
【PR】『Python』を学べる企業・個人向けのプログラミングコース
DocCommentの基本的な書き方
DocCommentの基本的な書き方は、/**で開始し*/で終了する形式で、関数やクラスの直前に記述します。コメントの1行目には関数の概要を記述し、その後に詳細な説明や各種タグを追加していきます。
<?php
/**
* ユーザー情報を取得する関数
*
* データベースからユーザーIDに基づいて
* ユーザー情報を取得します。
*/
function getUser($userId) {
// 処理内容
return $userData;
}
?>
上記のコードでは、getUser関数の直前にDocCommentを記述しています。各行の先頭には*を配置することで、視覚的に統一された形式でコメントを記述できます。
DocCommentは通常の複数行コメントと異なり、/**で開始することによって「IDE」や「ドキュメント生成ツール」が特別な扱いをします。関数の概要を1行目に簡潔に記述し、必要に応じて詳細な説明を追加することで、コードの可読性と保守性を向上させることができます。
@paramタグで引数を説明する
@paramタグは、関数やメソッドの引数に関する情報を記述するためのタグです。「@param データ型 変数名 説明」の形式で記述することによって、各引数の型と役割を明示的に文書化できます。
<?php
/**
* 税込価格を計算する関数
*
* @param int $price 商品の価格
* @param float $taxRate 税率(0.1で10%)
*/
function calculateTotalPrice($price, $taxRate) {
return $price * (1 + $taxRate);
}
?>
上記のコードでは、calculateTotalPrice関数の2つの引数について、@paramタグで型と説明を記述しています。$priceはint型で商品の価格を表し、$taxRateはfloat型で税率を表すことが明示されています。
@paramタグを使用することによって、IDEが関数呼び出し時に引数の型や説明を表示し、入力補完を提供できるようになります。複数の引数がある場合は、引数の順番通りに@paramタグを記述することで、関数の仕様を正確に伝えることができます。
@returnタグで戻り値を説明する
@returnタグは、関数やメソッドの戻り値に関する情報を記述するためのタグです。「@return データ型 説明」の形式で記述することによって、関数が返す値の型と内容を明示的に文書化できます。
<?php
/**
* ユーザーの年齢を計算する関数
*
* @param string $birthDate 生年月日(Y-m-d形式)
* @return int ユーザーの年齢
*/
function calculateAge($birthDate) {
$birth = new DateTime($birthDate);
$now = new DateTime();
$age = $now->diff($birth)->y;
return $age;
}
?>
上記のコードでは、calculateAge関数の戻り値について、@returnタグでint型のユーザー年齢を返すことを記述しています。@paramタグと組み合わせることで、関数の入力と出力の両方を明確に文書化できます。
@returnタグを適切に記述することによって、関数を使用する側は戻り値の型を事前に把握でき、型に応じた適切な処理を実装できます。戻り値が存在しない場合はvoid型を指定し、複数の型を返す可能性がある場合は、パイプ記号で区切って記述することも可能です。
※上記コンテンツの内容やソースコードはAIで確認・デバッグしておりますが、間違いやエラー、脆弱性などがある場合は、コメントよりご報告いただけますと幸いです。
ITやプログラミングに関するコラム
Dockerfileの基本的な使い方とビルド方法を簡単に解説
【初心者向け】データベースの基本的な作り方を簡単に解説
【PHP】PDOでMySQLに接続する方法を簡単に解説
【WordPress】絞り込み検索機能を自作する方法をサンプルコードと併せて解説
【PHP】コードの動作確認をローカル・オンラインで行う方法
MacでWordPressのローカル環境を構築する方法を解説
PHPで日本語の曜日を表示する方法を簡単に解説
【Mac用】miテキストエディタのインストール方法や使い方を解説
Photoshopで文字入れする方法と入力テキストの編集方法
ITやプログラミングに関するニュース
株式会社テンダがウェビナー登壇、AIとDX導入後の定着化ノウハウを解説
株式会社ペイロールが労務管理効率化セミナーを開催、本社人事のコア業務促進を支援
株式会社インフォ・クリエイツが無料ウェビナー開催、Webアクセシビリティの体制構築を解説
株式会社これからがオンラインイベント登壇、AIとSNSを活用した新卒採用戦略セミナーを開催
LRM株式会社がフィッシング対策協議会セミナーに参加、セキュリオのデモ体験を提供
Umee Technologiesが無料ウェビナー開催、AI活用の盲点と戦略立案のポイントを解説
株式会社M&Aナビがウェビナー開催、吸血型M&Aを防ぐための取り組みを解説
エムスリーがウェビナーを開催、サイバーエージェントCHOがエンゲージメント向上策を解説
株式会社ビザスクがウェビナー開催、三井化学のDX事例から経営と現場の変革を学ぶ
Fracta Japanが無料オンラインセミナー開催、ホワイトペーパーで水道業界の未来を解説
