PHPでのコメントアウトの基本と効果的なコメントの書き方

JavaScriptを有効にしてください

前書き

PHPプログラミングでは、コメントアウトはコードを理解しやすくするための重要な要素です。
この記事では、PHPでのコメントアウトの基本的な使い方と効果的な書き方について紹介します。

コメントアウトの基本

PHPでは、コメントはコード内で無視されるテキストの部分で、コードの説明やメモ、一時的なコードの無効化に使われます。

シングルラインコメント

シングルライン(一行)コメントは、//または#で始まります。これらのコメントは行末まで続きます。

1
2
3
4
5
// これはシングルラインコメントです
echo "Hello, World!";

# これもシングルラインコメントです
echo "PHPの学習を始めましょう!";

マルチラインコメント

マルチライン(複数行)コメントは、/*で始まり*/で終わります。これらのコメントは複数行に渡って使用できます。

1
2
3
4
5
6
/*
これはマルチラインコメントです。
複数行にわたる説明文や
一時的なコードの無効化に便利です。
*/
echo "複数行のコメント例";

実践的な例

コメントの基本的な書き方を学んだところで、ここからは実践的な使用例を見てみましょう。
ポイントは自分以外の人がコードを見た時に、コードの理解の助けになる書き方ができるようになることです。

関数の説明でのコメント利用

関数に対して、関数の目的、パラメーター、戻り値に関するコメントを追加します。
これにより、関数の使用方法や目的を明確にする方法を学びます。

1
2
3
4
5
6
7
8
9
/**
 * 数値を二倍にする関数
 * 
 * @param int $number 入力数値
 * @return int 入力を二倍にした結果
 */
function doubleNumber($number) {
    return $number * 2;
}

複雑なロジックの説明

複雑な条件文やループ処理にコメントを追加して、そのロジックの理解を助けます。
これにより、複雑なコードの部分をどのようにして他の人が理解しやすくするかを見ることができます。

1
2
3
4
5
6
foreach ($items as $item) {
    // 在庫が0より大きい場合のみ項目を表示
    if ($item['stock'] > 0) {
        echo $item['name'];
    }
}

TODOコメントの使用法

TODOコメントは、将来の改善、機能の追加、バグの修正など、コードに対して後で行う必要がある作業をマークするために使用されます。
これらのコメントは、開発者が一時的に作業をスキップするか、あるいは後で取り組む必要があるタスクを追跡するためのものです。

使用法の詳細

タスクの追跡: TODOコメントは、特定の機能を実装するか、特定の問題を解決するために必要な作業を明記します。
優先度や期限の指定: 優先度や期限を含めることで、TODO項目の緊急性を示すことができます。
責任者の指定: 誰がそのタスクを担当するのかを示すことができます。

コード例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// TODO: 高優先度で実装する必要がある機能を追加
// TODO: [2024-03-01] にレビューを行い、必要に応じてリファクタリングする
// TODO: @mofumofu がバグ修正を担当

/**
 * 未実装の機能に関する一時的なプレースホルダー関数
 * TODO: 実装を完了させる
 */
function futureFeature() {
    // 現時点では何もしない
}

// TODO: 非効率的なロジックを改善する
function inefficientLogic() {
    // 現在のロジック...
}

非推奨の機能に関するコメント

非推奨の機能に関するコメントは、将来的に削除される予定の機能や、使用を避けるべき古いメソッドを指摘するために使用されます。
これらのコメントは、開発者に対して、代わりに新しい、より効果的な方法を使うよう促します。

使用法の詳細

非推奨の理由: なぜその機能が非推奨になったのかを説明します。
代替案の提供: 代わりに使用すべきメソッドや機能を示します。
非推奨の日付: いつからその機能が非推奨になったのかを記録します。

コード例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
/**
 * この関数は非推奨であり、将来的に削除されます。
 * 代わりに `newFunction` を使用してください。
 * @deprecated since 2023-01-01
 */
function deprecatedFunction() {
    // 古いロジック...
}

/**
 * 新しい、推奨される方法
 */
function newFunction() {
    // 新しいロジック...
}

クラスのコメント

クラスに関するコメントでは、そのクラスの目的、責任、およびクラスがどのような問題を解決するのかについて説明します。

1
2
3
4
5
6
7
8
9
/**
 * 従業員を表すクラス
 * 
 * このクラスは従業員の基本情報(名前、部署、役職など)を保持し、
 * 従業員に関連する操作(昇給処理、部署の変更など)を提供します。
 */
class Employee {
    // クラスのプロパティとメソッド...
}

メソッドのコメント

メソッドに関するコメントでは、メソッドが何をするのか、どのようなパラメータを受け取り、どのような値を返すのかを説明します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/**
 * 従業員の給与を昇給する
 * 
 * このメソッドは指定されたパーセンテージで従業員の給与を昇給します。
 * 昇給後の給与額を計算し、更新します。
 *
 * @param float $percentage 昇給率(パーセンテージ)
 */
public function raiseSalary($percentage) {
    // 昇給処理のロジック...
}

インターフェースのコメント

インターフェースに関するコメントでは、そのインターフェースがどのような契約を提供するのか、実装クラスがどのようなメソッドを提供しなければならないのかを説明します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
/**
 * 支払い処理のインターフェース
 * 
 * このインターフェースは支払い処理を実装するための契約を定義します。
 * すべての支払い方法(クレジットカード、銀行振込など)はこのインターフェースを実装する必要があります。
 */
interface PaymentInterface {
    /**
     * 支払いを処理する
     * 
     * @param float $amount 支払額
     */
    public function processPayment($amount);
}

コメントの典型的なミスと避け方

過剰なコメントを避ける

コードが自己説明的であるべきだという原則について説明します。
コメントはコードを補足するものであり、コードから明白なことを再説明する必要はありません。

1
2
3
4
5
6
7
8
9
/**
 * 数値を二倍にする関数
 * 
 * @param int $number 入力数値
 * @return int 入力を二倍にした結果
 */
function doubleNumber($number) {
    return $number * 2; // numberを2倍にする << こういったコメントは必要ない
}

定期的なコメントの見直し

コードの変更に伴い、コメントも更新する必要があることを意識しましょう。
古いまたは誤ったコメントはコードの理解を妨げる可能性があるためです。
仕様変更が入った際は、以前に記載したコメントも書き直す必要が出てきます。

例えば下記のように在庫0の条件の他に販売停止の条件を加えた場合などです。

1
2
3
4
5
6
foreach ($items as $item) {
    // 在庫が0より大きい場合のみ項目を表示
    if ($item['stock'] > 0 && !$item['isDiscontinued']) {
        echo $item['name'];
    }
}

コードは変わっていますが、コメントは変わっていません。
急な仕様変更で急いで修正をする場合、コメント部分は後で直せばいいやみたいになるケースはままありますので、
直し忘れが無いように注意しましょう。

これは下記のように書き直さないとだめですね。

1
2
3
4
5
6
foreach ($items as $item) {
    // 在庫が0より大きい、かつ販売停止になっていない場合のみ項目を表示
    if ($item['stock'] > 0 && !$item['isDiscontinued']) {
        echo $item['name'];
    }
}

超複雑なロジックの説明

先ほどの「在庫が0より大きい」といったロジックは、コメントが書かれていなくてもプログラマであればすぐに理解できると思いますが、
例えば下記のようなプログラムだとどうでしょうか?

1
2
3
4
5
6
7
8
9
function fibonacci($n) {
    if ($n <= 1) {
        return $n;
    }

    return fibonacci($n - 1) + fibonacci($n - 2);
}

echo fibonacci(10);

こちらはフィボナッチ数列を計算する関数ですが、数学の知識に長けていないとすぐに理解できないかと思います。
こういったかなり複雑なロジックの場合「動いているからいいや」となりコメントを書かなくなる人が多いです。

どちらかというとこういうケースほどコメントを書く重要性が増してきます。

下記のようにコメントが書いてあると数学の知識がなくてもある程度理解ができますし、コードの保守もしやすくなります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/**
 * フィボナッチ数列を計算する関数
 * 
 * この関数は、再帰を使用してフィボナッチ数列のn番目の数値を計算します。
 * フィボナッチ数列では、最初の2つの数は0と1であり、以降の数は前の2つの数の合計となります。
 * 再帰的なアプローチは理解しやすいですが、大きなnに対しては効率が悪くなる可能性があります。
 * そのため、実用的な用途ではメモ化や動的プログラミングのテクニックを使用することが推奨されます。
 *
 * @param int $n フィボナッチ数列のn番目の数を指定
 * @return int フィボナッチ数列のn番目の数値
 */
function fibonacci($n) {
    // ベースケース: nが0または1の場合、n自身を返す
    if ($n <= 1) {
        return $n;
    }

    // 再帰的に前の2つの数を計算し、その合計を返す
    return fibonacci($n - 1) + fibonacci($n - 2);
}

// 例: 10番目のフィボナッチ数を計算する
echo fibonacci(10);

チームで決めたルールはきちんと守る

一貫性の重要性: プロジェクトやチームにおけるコメントのスタイルガイドの重要性について触れ、統一されたコーディングスタイルの採用を勧めます。

1人1人が独自の書き方をすると、コードレビュー時の負担が増大してしまいます。
それを防ぐためにコメントは会社で記載のルールを決めている場合がほとんどです。
レビュアーの負担を減らすためにもルールを守ってコメントを記載するように心がけましょう。

ルールがない場合は簡単なルールを決めてからコーディングを始められるようにしっかりと提案できるようになることも重要です。

ChatGPTに書いてもらう

もしどういう書き方をしたらいいのかパッと思いつかない時は、ChatGPTに投げて提案してもらうのもありです。
コメントを書く足掛かりになるかも知れません。
※ChatGPTに書いてもらう際の注意点として、ChatGPTにソースコードを投げてもいいか会社や顧客に確認をしてから使用するようにしましょう。顧客に納品するソースコードの場合ChatGPTのような第三者へのコードの送信は情報漏洩といった重大な契約違反になる可能性があります。

ChatGPTのプロンプトに投げる時は、例えば、

下記コードにコメントを書いて
※ここにコードを貼り付ける

Shiftキー+Enterでプロンプト内で改行ができるので、そこでコードを貼り付けてください。(改行しなくても行けると思いますが)

例えば下記のコードを上記プロンプトでChatGPTに投げると、

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
function fetchUserData($userId) {
    $url = "https://jsonplaceholder.typicode.com/users/" . $userId;
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    $data = curl_exec($ch);
    curl_close($ch);
    return json_decode($data, true);
}

$userData = fetchUserData(1);
echo "Name: " . $userData['name'] . "\n";
echo "Email: " . $userData['email'] . "\n";

下記のようにコメントを付けてくれます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
/**
 * 指定されたユーザーIDに対応するユーザーデータを取得する関数
 * 
 * @param int $userId 取得したいユーザーのID
 * @return array ユーザーデータを含む連想配列
 */
function fetchUserData($userId) {
    // ユーザーデータを取得するURLを構築
    $url = "https://jsonplaceholder.typicode.com/users/" . $userId;

    // cURLセッションを初期化
    $ch = curl_init($url);

    // 戻り値を文字列として直接受け取るためのオプションを設定
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // ヘッダーを結果に含めないようにするオプションを設定
    curl_setopt($ch, CURLOPT_HEADER, 0);

    // URLの内容を取得
    $data = curl_exec($ch);

    // cURLセッションを終了
    curl_close($ch);

    // 取得したデータ(JSON形式)をPHPの配列に変換して返す
    return json_decode($data, true);
}

// ユーザーID 1 のデータを取得
$userData = fetchUserData(1);

// 取得したユーザーデータから名前とメールアドレスを表示
echo "Name: " . $userData['name'] . "\n";
echo "Email: " . $userData['email'] . "\n";

こんな風にいい感じでコメントを付けてくれます。
もし過剰だなと感じたら、「過剰なコメントを取り除いて」と書けば、

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
/**
 * 指定されたユーザーIDのユーザーデータを取得します。
 *
 * @param int $userId ユーザーのID
 * @return array ユーザーデータの連想配列
 */
function fetchUserData($userId) {
    $url = "https://jsonplaceholder.typicode.com/users/" . $userId;
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, 0);
    $data = curl_exec($ch);
    curl_close($ch);
    return json_decode($data, true);
}

$userData = fetchUserData(1);
echo "Name: " . $userData['name'] . "\n";
echo "Email: " . $userData['email'] . "\n";

関数の説明と引数の説明のみになりました。
ここから自分で必要なコメントを追記していくやり方もありだと思います。

まとめ

この記事では、PHPにおけるコメントの基本から始まり、効果的なコメントの書き方に至るまで、幅広いトピックをカバーしました。
コメントは単にコードにメモを残す以上の価値を持ち、コードの可読性を高め、将来のメンテナンスを容易にし、チームメンバー間でのコミュニケーションを促進します。

効果的なコメントは、良いコードを書くための重要なスキルの一つです。
この記事で紹介したガイドラインを実践することで、あなたのPHPプログラミングスキルをさらに向上させ、よりメンテナンスしやすく、チーム内で共有しやすいコードを書くことができるでしょう。
コメントは時間を節約し、エラーを減らし、最終的にはより高品質なソフトウェアの開発に貢献します。
これらのコメントのベストプラクティスをぜひ活用してください。


スポンサーリンク

共有

もふもふ
著者
もふもふ
プログラマ。汎用系→ゲームエンジニア→Webエンジニア→QAエンジニア