はじめに (対象読者・この記事でわかること)

この記事は、PHPでコードを書くすべての開発者、特にチーム開発やオープンソースへの貢献を考えている方を対象としています。
PHPの公式コーディング規約（PSR‑12）や、社内・プロジェクト独自のスタイルガイドで「コメントの前後にスペースを入れるかどうか」といった細かなルールがありますが、実際にどのように記述すれば良いのか、また自動でチェックする手段があるのか戸惑うことが多いです。

本記事を読むことで、
コメントの空白に関する公式規約とその背景
 PHPCS でコメント空白チェックを有効化し、CI に組み込む方法
* よくあるミスとその対処法
が具体的に理解でき、コードベースの一貫性を保つための実装がすぐにできるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。
PHP の基本的な文法とコメント記法（//、/* */、/** */）
 Composer の基本操作と vendor/bin 以下のコマンド実行経験
* GitHub Actions や GitLab CI など、何らかの CI ツールを使ったことがある

コメント空白に関するコーディング規約の概要

PHP のコーディング規約として広く採用されている PSR‑12 では、コメントの書き方にいくつかの細かいガイドラインが定められています。中でも「コメントマーカー（//、#、/*）の直後に必ず空白を入れる」ことが明記されており、これは可読性と統一感を維持するためです。

具体例を挙げると、次の2つは PSR‑12 に準拠した書き方です。 

Php

// 正しい例: コメントマーカーの後に半角スペース
// 変数の初期化

# 正しい例: ハッシュコメントでもスペース必須
# デバッグ用の出力

一方、次のようにスペースが抜けていると警告対象となります。 

Php

//誤った例: 空白なし
#誤った例:空白なし
/*誤: 空白なし*/ $value = 10;

PSR‑12 では、/* … /（DocBlock）についても同様に、開始マーカーと最初のアスタリスクの間、各行のアスタリスクの後に必ずスペースを入れることが推奨されています。これは IDE の自動補完やドキュメント生成ツール（phpDocumentor 等）でも期待される形式です。

しかし、実務ではプロジェクト独自の例外や、過去に書かれたコードが多数存在し、すべてを手作業で修正するのは非現実的です。そこで、自動チェックツールと自動整形ツールを組み合わせて、規約違反を継続的に検出・修正できる体制を整えることが重要です。

コメント空白チェックの自動化と実装手順

以下では、PHP_CodeSniffer（PHPCS）を利用してコメント空白ルールを検出し、CI に組み込むまでの具体的な手順を示します。各ステップで実際のコード例やコマンドを交えて解説します。

ステップ1：PHPCS と PSR‑12 ルールセットの導入

まずプロジェクトのルートで Composer を使い、PHPCS と PSR‑12 のルールセットを開発依存としてインストールします。

Bash

composer require --dev squizlabs/php_codesniffer
composer require --dev phpcompatibility/php-compatibility

インストールが完了したら、vendor/bin/phpcs が利用可能になります。PSR‑12 の標準ルールは --standard=PSR12 オプションで呼び出せます。

Bash

vendor/bin/phpcs --standard=PSR12 src/

このコマンドを実行すると、コメントの空白違反だけでなく、インデントや命名規則など PSR‑12 全体の違反が一覧で出力されます。

ステップ2：コメント空白だけを対象にしたカスタムスニッフの作成

プロジェクトによってはコメント空白以外のルールは緩くしたいケースがあります。その場合、PHPCS のカスタムスニッフを作成して特定のエラーだけを有効化します。

  1. phpcs.xml.dist をプロジェクト直下に作成し、以下のように設定します。
Xml

<?xml version="1.0"?>
<ruleset name="ProjectCustom">
    <description>プロジェクト独自のコーディング規約</description>
    <rule ref="PSR12.Comment" />
    <!-- 他の PSR12 ルールは除外 -->
    <exclude name="PSR12.Files.EndFileNewline"/>
    <exclude name="PSR12.ControlStructures.ControlStructureSpacing"/>
</ruleset>
  1. vendor/bin/phpcs を実行すると、コメント空白に関する警告だけが表示されます。
Bash

vendor/bin/phpcs -s --standard=phpcs.xml.dist src/

-s オプションはエラーがどのスニッフから出たかを明示的に表示します。PSR12.Comment がコメント空白に関わるスニッフです。

ステップ3：自動整形（Fixer）で違反箇所を修正

PHPCS には --report=summary などのレポート形式がありますが、phpcbf（PHPCS の自動修正ツール）を併用すると、検出されたコメント空白違反を自動で修正できます。

Bash

vendor/bin/phpcbf --standard=phpcs.xml.dist src/

実行後、修正されたファイルは差分が残りますので、git diff で確認し、問題がなければコミットします。

ステップ4：CI パイプラインへの組み込み

GitHub Actions を例に、プッシュやプルリクエスト時に自動でコメント空白チェックを走らせるワークフローを作成します。.github/workflows/phpcs.yml に以下を追加してください。

Yaml

name: PHP CodeSniffer

on: [push, pull_request]

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: mbstring, intl
      - name: Install dependencies
        run: composer install --no-progress --no-suggest --prefer-dist
      - name: Run PHPCS
        run: vendor/bin/phpcs --standard=phpcs.xml.dist src/

この設定により、CI がコメント空白の違反を検出した場合、ジョブが失敗し、プルリクエストのチェックとして表示されます。失敗した場合はローカルで phpcbf を実行し、修正後に再度プッシュすれば自動的に合格へと移ります。

ハマった点やエラー解決

1. PHPCS が PSR12.Comment を認識しない

症状：phpcs.xml.dist に <rule ref="PSR12.Comment" /> を書いたが、実行時に “Rule not found” エラーが出た。
原因：PHPCS のバージョンが古く、PSR‑12 のコメントルールが別名（Squiz.Commenting など）で提供されている。
解決策：最新の PHPCS にアップデートし、再度実行する。

Bash

composer update squizlabs/php_codesniffer

2. phpcbf が一部のコメントだけ修正できない

症状：/** で始まる DocBlock の先頭行だけがスペースなしのまま残る。
原因：phpcbf の自動修正は // と # のみ対象とし、DocBlock の開始マーカーは対象外になることがある。
解決策：phpcbf の代わりに phpcs --standard=PSR12 --report=diff で差分を取得し、手動で修正するか、カスタムスニッフで DocBlock の開始行も検知するように拡張する。

3. CI で vendor/bin/phpcs が見つからない

症状：GitHub Actions のジョブが “command not found: vendor/bin/phpcs” と失敗。
原因：composer install が --no-dev で走っているか、vendor ディレクトリがキャッシュされていない。
解決策：composer install をデフォルト（dev 依存含む）で実行し、actions/cache を利用して vendor ディレクトリを保持する。

Yaml

- name: Cache Composer dependencies
  uses: actions/cache@v3
  with:
    path: vendor
    key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}
    restore-keys: ${{ runner.os }}-composer-

解決策のまとめ

  1. PHPCS と PSR‑12 の導入 → コメント空白違反を検出できる基盤を構築。
  2. カスタムルールセットでコメント空白だけを対象に絞り込み、不要な警告を抑制。
  3. phpcbf による自動修正で手作業を最小化。
  4. CI への組み込みでプッシュ時に即座にフィードバックを取得し、コードベースの一貫性を保つ。

これらを順に実装すれば、プロジェクト全体で「コメントの前後にスペースを入れる」規約が自動的に守られ、レビューコストが大幅に削減されます。

まとめ

本記事では、PHP のコメントにおける空白ルール（PSR‑12）と、PHPCS を用いた自動チェック・自動修正のフローを詳しく解説しました。

  • コメントマーカーの直後は必ず半角スペースを入れることが PSR‑12 の基本要件。
  • PHPCS の PSR12.Comment ルールで空白違反を検出し、phpcbf で自動整形が可能。
  • カスタム phpcs.xml.dist により、コメント空白だけを対象に絞り込み、CI へシームレスに組み込める。

この手順を導入すれば、コードレビューの負担が減り、チーム全体のコード品質が向上します。次回は、PHPDoc のフォーマット統一と、phpDocumentor 連携について掘り下げた記事を予定しています。

参考資料