概要

メソッドコメントちゃんと書いてほしい
コードレビューめんどくさい、自動化できるとこは自動化したい
code_sniffer使って定義しておけば、どうにかなるはず
（PHPStormに整形させたり、規約に反していれば警告だしたりしてくれる）

などの気持ちを、調べながら実装していった。
ちょっとルールを追加したり、一部の検査を除外したかったりしただけなのに、ずいぶんつまずいたのでメモを残しておく。

phpcs.xml(暫定/Laravel用)

<?xml version="1.0"?>
<ruleset name="MyPSR12">
    <description>メソッドコメントなどをきちんとかきましょうの規約</description>

    <!-- app,config,routes,tests のみ検査対象 -->
    <exclude-pattern>*/bootstrap/*</exclude-pattern>
    <exclude-pattern>*/database/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/public/*</exclude-pattern>
    <exclude-pattern>*/resources/*</exclude-pattern>
    <exclude-pattern>*/storage/*</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>

    <!-- テストコードは暫定で除外 -->
    <exclude-pattern>*/tests/*</exclude-pattern>
    <!-- Laravelインストール時に作成されるコードの一部をチェック対象から除外 -->
    <exclude-pattern>*/app/Console/Kernel.php</exclude-pattern>
    <exclude-pattern>*/app/Http/Middleware/RedirectIfAuthenticated.php</exclude-pattern>
    <exclude-pattern>*/app/Http/Middleware/Authenticate.php</exclude-pattern>
    <exclude-pattern>*/app/Http/Middleware/TrustProxies.php</exclude-pattern>
    <exclude-pattern>*/app/Http/Middleware/VerifyCsrfToken.php</exclude-pattern>

    <!-- Include the whole PSR12 standard except FunctionComment, which we override -->
    <rule ref="PSR12"></rule>

    <!-- メソッドコメントを書きなさい -->
    <rule ref="Squiz.Commenting.FunctionComment">
        <!-- 細かすぎるとめんどいので除外 -->
        <exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamName"></exclude>
        <exclude name="Squiz.Commenting.FunctionComment.MissingParamComment"></exclude>
        <exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamType"></exclude>
        <exclude name="Squiz.Commenting.FunctionComment.TypeHintMissing"></exclude>
        <exclude name="Squiz.Commenting.FunctionComment.EmptyThrows"></exclude>
    </rule>

    <!-- メンバ変数にコメントを書きなさい -->
    <rule ref="Squiz.Commenting.VariableComment"></rule>

</ruleset>

概念/設計の理解

code_snifferでは、コーディング規約を大まかに以下の3階層に分けて定義できるようだ。

Standard
Sniffs
Error Code

Standard

Standardは一番上の階層で、「規約」の概念そのものに対応している。例えば、PSR1、PSR2、PSR12などがこの階層で定義されている。 phpcs を -i 付きで叩くとstandardが一覧で表示される。

phpcs -i

つまり、自分用にコーディング規約を定義したい場合はStandardを1つ（xmlファイルを1枚）作ればよい。

Sniff

一連のルールを定義する。
また、Sniffsは自由に名前空間を設定できるっぽいので、階層が1つ以上になる。例えば
Squiz.Commenting.FunctionComment
が、メソッドコメントに関するルールに対応している。

Error Code

これの説明がどこにも無いので非常に困った。
Sniffには、検査によって生じうるエラーが複数定義されていて、それらのエラーは必ずError Codeを持っている。

例えば、
Squiz.Commenting.FunctionComment.EmptyThrows
は、

Standard : Squiz
Sniffs : Commenting.FunctionComment
Error Code: EmptyThrows
を示している。

Squiz.Commenting.FunctionComment と書いた場合は、Sniffを指し、
Squiz.Commenting.FunctionComment.EmptyThrows　と書いた場合はError Codeを指すため、非常にわかりにくい。

Sniffの名前空間が自由っぽいので、階層を見てもSniffなのかError Codeなのかの見分けがつかないのだ。

まとめ

今の所、以下のように理解した。

xml上では Standard がRuleset に対応している。
Standard は、適用する複数の Sniffs を設定できる。
Sniffには、複数のError Code が紐付いている。
Error Codeだけを指定して検査することはできないっぽい
- なぜなら、Error Code は Sniff ではないから（たぶん）
- なので、Ruleset にSniffを入れて、Sniffの中に除外するError Codeを指定、という構造にすれば意図通り動く。

なお、Error Codeはドキュメントが揃ってないので、諦めて
vendor/squizlabs/php_codesniffer/src/Standards の中を見ましょう。

ググり

検索ワード「FunctionComment sniffs」

全く同じ疑問を持った外人がおこってた
Subsniffs undocumented and undiscoverable
https://github.com/squizlabs/PHP_CodeSniffer/issues/2213
（ドキュメント整備しろとか言ってる暇があったらxml書いてプルリク出せば？的なこと言われてるっぽい）

Sniffの下に、Error Codeの階層がある
-e スイッチ付きで phpcs 叩くとスニフ一覧が見れるぞ

phpcs -e

オプションつければドキュメントっぽいテキストも出力できる

phpcs --standard=Squiz --generator=Text

I've become aware that sniffs such as Squiz.Commenting.FunctionComment contain many sub-sniffs, including, but not limited to:

超適当訳：スニフに、サブスニフ的なの含まれてない？

Where can I find a complete list of sniffs and subsniffs and documentation of their behaviour?

どこに一覧あんの？

Those are not subsniffs, but error codes.

サブスニフじゃねえ、エラーコードだ

検索ワード「Squiz.Commenting.Function Error Code」

Finding PHP CodeSniffer rules
https://stackoverflow.com/questions/44918498/finding-php-codesniffer-rules

-s スイッチ付きで実行するとエラーコードが表示される

検索ワード「Sniffs php」

PHP Code SnifferのSniffを自作するにあたって知っておいてよかったこと
https://qiita.com/suin/items/34393032bb5f4cf49cbb

Sniff周りのディレクトリ構成がわかる。ソースコードを見るときに助かりそう