WordPress コーディングスタンダードの正式な書き方をまとめてみる

WordPress には WordPress Coding Standard (WPCS) なるものが存在します。公式によると、コードの一貫性を維持し、メンテナンス性を向上させ、読みやすくさせるためのものということです。

ですが実は、公式テーマの TwentySeventeen でさえ一部の Javascript ファイルでエラーが出てたり、コア内の PHP ファイルに至ってはかなりのエラーが存在したりします。

追記 : 2017年12月より、徐々に WPCS に沿うよう変更されており、現在では 95% 以上のコードが沿っているようです。詳細 - WordPress PHP now (mostly) conforms to WordPress Coding Standards – Make WordPress Core

今回、自作のテーマを WPCS に沿ったコードへ作り変えてみたので、やったことと思ったこといついての感想です。

WPCS 内には PHP, HTML, CSS, Javascript と全言語別に存在しますが、今回は PHP のルールに関してのみ触れます。

はじめに

WPCS 内には、以下の4つのルールが存在します。

• WordPress-Core
• WordPress-Extra
• WordPress-Docs
• ~~Wordpress-VIP~~

この中の "WordPress-VIP" に関しては WordPress.com の提供する有料サービスのようなもののためのプラクティスであり、普通の使い方をしているのであれば気にする必要はありません。WPCS 1.0.0 のリリースに伴い、WordPress-VIP は deprecated となりました。

"WordPress-Core" はメインのコーディングスタンダードの内容、"WordPress-Extra" はそれにベストプラクティスを使うための拡張ルール、"WordPress-Docs" はさらに Doc コメントの書き方ルールを含めたもの、となります。

これら3つをまとめたものに "WordPress" というルールセットがあり、こちらが Core, Extra, Doc すべてをまとめたものです。すべてに対応する気がある場合、これを使っていくのが簡単です。

以下、Core と Extra の内容をまとめて紹介した後、Doc ルールセットに従うためのコメントの書き方を紹介していきます。

スポンサーリンク

書き方

ここではあくまで引っかかりやすそうなもののみ取り上げています。完全な訳は WordPress Codex 日本語版 を参照してください。

インデント

インデントにはスペースではなくタブを使います。これは絶対です。

並んでいる複数行のコードがあり、見やすくなるのであれば、出だしを揃えるためにイコールの前にスペースを足すことが出来ます。

$my_array = array(
    'foo'   => 'hoge',
    'foo2'  => 'hoge2',
    'foo3'  => 'hoge3',
    'foo34' => 'hoge4',
);

例えばこんな感じ。'foo' のあとには3スペース、'foo34' のあとには1スペースのような形です。

ただし、イコールのあとのスペースは必ず1つのみとなります。

また、配列のキーはすべて一行ごとに改行が必要です。

改行ルール

大カッコはすべて行で文末に来なくてはいけません。つまり、

// 間違い
function foobar() { echo 'HI'; }

のような書き方は出来ず、一行ごとに改行が必要となります。

シングルクオートとダブルクオート

可能な限りシングルクオートを使用します。また、クオートのエスケープは基本的にせず、両方を併用することでエスケープを回避します。
例えば:

echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';
echo "<a href='$link' title='$link_title'>$link_name</a>";

中括弧のスタイル

if 文の次に elseif が続く場合、if 文の閉じカッコと elseif の初めは同じ行になっていなければいけません。(※ else if ではなく elseif を使用します)

if ( condition ) {
    action1();
} elseif ( condition2 ) {
    action2a();
    action2b();
}

また、インラインのシングルステートメントを使用する場合、コロンの前後には必ずスペースが必要です。

<?php if ( have_posts() ) : ?>
    <div class="hfeed">
        <?php while ( have_posts() ) : the_post(); ?>
            <article id="post-<?php the_ID() ?>" class="<?php post_class() ?>">
                <!-- ... -->
            </article>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

PHP の開始タグ・終了タグ

複数行の HTML を PHP 内に埋め込む場合、PHP の開始タグ・終了タグはそれぞれ新たな行で始まっている必要があります。

function foo() {
    ?>
        <div>
        <?php
        echo bar(
            $baz,
            $bat
        );
        ?>
       </div>
    <?php
}

1行のみの HTML の場合は改行は必要ありません。

ショートハンドの PHP タグは使用禁止

ショートハンドの PHP タグは使用してはいけません。

だめ: <?= $var ?>

行末のスペースを排除

ファイル内のすべての行の最後に無駄なスペースをつけてはいけません。必ず削除しましょう。

スペースの使い方

スペースは コンマのあと、と、論理演算子、文字列演算子 (連結演算子など)、比較演算子、代入演算子の両側に必要です。

例えば、

foreach ( $foo as $bar ) { ...

if ( ! function_exists( 'foo' ) ) { ...

! の前後にもスペースが必要なことに注意してください。

ただし、function_exists や empty のようなものにはカッコ内のみのスペースが必要で、カッコの前後には必要ありません。

また、配列要素を参照する場合、[] 内が文字列・数値以外の場合にのみスペースを挿入してください。

$x = $foo['bar']; // 正しい
$x = $foo[ 'bar' ]; // 間違い

$x = $foo[0]; // 正しい
$x = $foo[ 0 ]; // 間違い

$x = $foo[ $bar ]; // 正しい
$x = $foo[$bar]; // 間違い

データベース

データベースから直接データを取ってくることは避けてください。WordPress にはいくつかのデータベースから情報を取ってくるための関数が定義されています。そちらを使用してください。

データベースからデータを取ってくる必要があるものの、それが WordPress 実装されていない場合は、wp-hackers mailing list へメッセージを送ると、次のバージョンでその為の関数を作ってくれるかもしれない、とのことです。

ネーミング規則

変数名、アクション名、関数名にはすべて小文字を使用してください (キャメルケースは認められません)。単語と単語の間はアンダースコアを使用して区分けます。また、名前をより明確に分かりやすくするため、可能な限り単語の省略はしないでください。

ファイル名はすべて小文字を使用し、単語間はハイフンで区切ります。

クラス名では、アンダースコアで区切られた単語は大文字で始めてください。また、頭文字語は大文字にしましょう。
新しいクラスを宣言する場合、class-[クラス名].php ファイル内で宣言する必要があります。例えば CD_Custom_Content クラスであれば、

class-cd-custom-content.php

ファイル内で定義されていないといけません。この場合でもファイル名には小文字を使います。

分かりやすい関数の引数を使う

関数を呼び出す際に、ただの true, false より、文字列の方が推奨されます。

例えば、

// 良くない例
function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true );
eat( 'dogfood', false );

この例だと、関数の引数、true, false の意味がわかりにくく伝わりにくいので、

// 良い例
function eat( $what, $speed = 'slowly' ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'quickly' );

slowly や quickly のような具体的な名前の引数を使用するべきです。

ファイルの最終行に空行を挿入

各ファイルの最終行には空行 (スペースもなし) を挿入してください。

ヨーダ記法

ここは賛否両論ありそうなところですが、WordPress コーディングスタンダードではヨーダ記法での記述が要求されます。

ヨーダ記法とは、定数や文字列を左側に、変数を右側に置く記述方法です。

例えば:

if ( true == $the_force ) {
    $victorious = you_will( $be );
}

のように記述します。

定数を左に置くことで、誤って条件式内で変数への代入をしてしまうミス ($the_force = true のように) を防ぐため、だそうです。

ちなみにヨーダ記法は ==, ===, !=, !== のときにのみ使用され、< や <= 等では使う必要はありません。

ドキュメンテーションコメント

こちらも引っかかりやすそうなもののみ述べます。完全な訳は WordPress Codex 日本語版 を参照してください。

コメントの基本

/* */ と // の違い

/* */ はブロックコメントです。これを使う場合、開始タグと閉じタグはそれぞれ新しい行に配置されていなくてはなりません。

// はインラインコメントです。一行のみの短いコメントを記述する際に記述します。

基本的にコメントを書く際、行末にピリオド、クエスチョンマーク、エクスクラメーションマークのいずれかで終わっていなければいけません。

ファイルの Doc コメント

すべてのファイルの先頭に、そのファイルが何であるかを表すドキュメンテーションコメントが必要です。

例えばこんな感じ。

/**
 * Summary.
 * 
 * Description.
 * 
 * @since 1.0.0
 * @package WordPress
 */

アスタリスクの前には必ず空白が一つ必要です。また、閉じたあとには一行分行を空けてください。例えば single.php では、

<?php
/**
 * The template for displaying single articles.
 *
 * @since 1.0.0
 * @package coldbox
 */

?>

<?php get_header(); ?>

となります。

@package には単語間をアンダースコアで区切ったテーマ名、たとえば @package Twenty_Seventeen のように書きます。

パッケージ名はファイル Doc コメントでのみ必須です。

関数のドキュメンテーションコメント

すべての関数の前に、その関数の役割の説明と、引数がある場合はそれの説明を書いた Doc コメントが必要です。こんな感じに書きます。

/**
 * Summary.
 *
 * Description.
 *
 * @param string $var Description.
**/
function ( $var ) { ...

Summary (概要) と Description (説明) とありますが、必須なのは Summary のみで description は必須ではありません (多分)。

これは本当に関数の直前 (コメントの終わりと関数のはじめに一行すら開けては駄目) にかくので、function_exists を使っていたとしても、その if 文の中に Doc コメントを書くことになります。

クラスのドキュメンテーションコメント

クラスを宣言する際にも、それに対するクラスの説明を書く必要があります。基本的は書き方は上2つとほぼ変わりありません。

/**
 * Summary.
 * 
 * Description.
 * 
 * @since 1.0.0
 */

長い条件文のとじカッコでの明示

長い if 文や foreach 文の終わりの}には、それが何の綴じカッコであるかを明示する必要があります。例えば:

if ( condition ) {
    do something...
    ....
    ....
    ....
    ....
    ....
} // End if().

のように書きます。

スポンサーリンク

感想

今回自作の Coldbox テーマを WPCS に沿うように直す作業をしたんですが、もともと俺ルールで書いていたエラー出まくりのコードを一個ずつ直したので結構辛かったです。

ですがこうやって躓いた部分を書き出してみると何気にそこまで難しい点はなく、一度慣れてしまえばある程度これに沿ったコードが書けそうな感じです。これからはこれで書いてみてもいいかと思いました。

PHP Code Sniffer を使った WordPress Coding Standard の構文エラーチェック & 自動修正に関する記事を書きました！

PHP CodeSniffer を使ってWPコーディングスタンダードのエラーをチェック&自動修正しよう [3.x 対応]

参考リンク

PHP Coding Standards – Make WordPress Core
PHP コーディング規約 - WordPress Codex 日本語版 (日本語訳)

PHP Documentation Standards – Make WordPress Core
PHP ドキュメント規約 - WordPress Codex 日本語版