A.4. コーディングスタイル

A.4.1. PHP コードの境界

PHP のコードの区切りには、標準 PHP タグを常に使用しなければなりません。

<?php

?>

短いタグは決して使用してはいけません。 PHP コードのみからなるファイルでは、終了タグ ("?>") は決して含めてはいけません (項A.2.1. 「全般」 を参照ください)。

A.4.2. 文字列

A.4.2.1. 文字列リテラル

文字列がリテラルである (変数の展開などが含まれない) 場合は、アポストロフィあるいは「シングルクォート」 で文字列を囲まなければなりません。

$a = '文字列の例';

A.4.2.2. アポストロフィを含む文字列リテラル

リテラル文字列自体にアポストロフィが含まれている場合は、 引用符あるいは「ダブルクォート」で文字列を囲んでもかまいません。 特に SQL 文などでこのような場合がよくあるでしょう。

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

アポストロフィをエスケープするよりも、上の構文のほうがお勧めです。

A.4.2.3. 変数の展開

変数の展開を行うには、次の 2 とおりの方法を使用します。

$greeting = "こんにちは $name さん。ようこそ!";

$greeting = "こんにちは {$name} さん。ようこそ!";

一貫性を保つため、以下の形式は許可されません。

$greeting = "こんにちは ${name} さん。ようこそ!";

A.4.2.4. 文字列の連結

文字列の連結には "." 演算子を使用します。コードを読みやすくするため、 "." 演算子の前後には常にスペースを入れなければなりません。

$company = 'Zend' . 'Technologies';

文字列を "." 演算子で連結する際には、コードを読みやすくするために ひとつの文を複数行に分けることもできます。そのような場合は、 2 行目以降の行頭にスペースを入れ、各行の "." 演算子が最初の行の "=" 演算子と同じ位置にくるようにしなければなりません。

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

A.4.3. 配列

A.4.3.1. 数値添字の配列

添字として負の数を使用してはいけません。

数値添字の配列の添字は、0 以上の任意の数から始めることができます。 しかし、常に 0 から始めるようにすることを推奨します。

array を使用して数値添字の配列を宣言する場合は、 コードを読みやすくするため、 要素を区切るカンマの後にスペースを入れなければなりません。

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');

"array" を使用して、複数行にまたがる配列を宣言することも可能です。 その場合は、2 行目以降の行頭にスペースを入れ、 各行の開始位置が以下のようになるようにしなければなりません。

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);

A.4.3.2. 連想配列

連想配列を array で宣言する場合には、 適宜改行をいれて複数行で宣言するようにしましょう。その場合は、 2 行目以降の行頭などにスペースを入れ、 キーと値の位置がそれぞれ揃うようにしなければなりません。

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

A.4.4. クラス

A.4.4.1. クラス宣言

クラス宣言は、以下の規約に従わなければなりません。

開始波括弧は常にクラス名の下に書かなければなりません ("one true brace" 形式)。

PHPDocumentor の標準形式のドキュメントブロックがなければなりません。

クラス内のコードは、すべて空白 4 文字で字下げします。

ひとつの PHP ファイルにはクラス定義をひとつだけ含めるようにします。

クラスファイルの中にクラス以外のコードを追加することもできますが、 お勧めしません。このような場合には、クラス定義とその他のコードの間に 空行を 2 行挿入しなければなりません。

これらの条件を満たすクラス宣言の例です。

/**
 * これがドキュメントブロックです
 */
class SampleClass
{
    // クラスのすべての内容は、
    // 空白 4 文字の字下げを使用します。
}

A.4.4.2. クラスのメンバ変数

メンバ変数は、以下の命名規約に従わなければなりません。

クラス内で宣言されるすべての変数は、クラスの最初、 つまり関数宣言の始まる前になければなりません。

var は使用してはいけません。メンバ変数は、常に privateprotected あるいは public を使用して宣言してください。 変数を public にして直接アクセスすることも可能ですが、推奨されません。 代わりにアクセサ (set/get) を使用してください。

A.4.5. 関数およびメソッド

A.4.5.1. 関数およびメソッドの宣言

関数は、以下の命名規約に従わなければなりません。

クラス内の関数は、必ず privateprotected あるいは public のいずれかを使用して宣言しなければなりません。

クラスと同様、 開始波括弧は常に関数名の下に書かなければなりません ("one true brace" 形式)。 関数名と引数指定の開始括弧の間には、空白を入れません。

グローバルスコープの関数は、できるだけ使用しないでください。

これらの条件を満たす、クラス内での関数定義の例です。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // 関数のすべての内容は、
        // 空白 4 文字の字下げを使用します。
    }
}

注意: 値の参照渡しは、関数宣言においてのみ可能です。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar(&$baz)
    {}
{}

実行時の参照渡しは禁止されています。

返り値は括弧で囲んではいけません。これは可読性を下げますし、 将来そのメソッドが参照を返すようになった場合にコードが壊れてしまいます。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * 間違いです
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * 正しい形式です
     */
    public function bar()
    {
        return $this->bar;
    }
}

A.4.5.2. 関数およびメソッドの使用法

関数の引数を指定する際は、引数を区切るカンマの後に空白をひとつ入れます。 例えば 3 つの引数を受け取る関数をコールする場合の例は、 以下のようになります。

threeArguments(1, 2, 3);

コール時に引数を参照渡しすることは禁じます。 関数への引数を参照渡しにする方法は、 関数宣言についての節を参照ください。

引数として配列を受け取る関数については、関数コールの中に "array" 構文を含め、それを複数行に分けることもできます。 そのような場合の記述法は、以下のようになります。

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);

A.4.6. 制御構造

A.4.6.1. If / Else / Elseif

if および elseif 系の制御構造では、 条件を指定する括弧の前に空白をひとつ入れなければなりません。 また、条件指定の括弧を閉じた後にも空白をひとつ入れなければなりません。

括弧で囲まれた条件文の中では、演算子の前後にも空白をいれなければなりません。 また、条件の論理的な区切りを明確にするため、 条件文の中でも積極的に括弧を使用することを推奨します。

開始波括弧は、条件文と同じ行に記述します。 終了波括弧は、常に改行してそれのみで記述します。 波括弧の中では、空白 4 文字の字下げを使用します。

if ($a != 2) {
    $a = 2;
}

"elseif" あるいは "else" を含む "if" 文の場合は、 以下の例のような書式になります。

if ($a != 2) {
    $a = 2;
} else {
   $a = 7;
}


if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
   $a = 4;
} else {
   $a = 7;
}

場合によっては、これらの文で波括弧が必要ない場合もあります。 しかし、このコーディング規約では、このような例外を認めません。 "if"、"elseif" あるいは "else" 文では、常に波括弧を使用しなければなりません。

"elseif" を使用することは可能ですが、推奨されません。代わりに "else if" を使用してください。

A.4.6.2. Switch

"switch" を使用した制御文では、 条件を指定する括弧の前に空白をひとつ入れなければなりません。 また、条件指定の括弧を閉じた後にも空白をひとつ入れなければなりません。

"switch" 文の中身は、空白 4 文字の字下げを使用します。 各 "case" 文の中身は、さらに 4 文字ぶん字下げします。

switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}

switch 文の default は、 決して省略してはいけません。

注意:case の最後に breakreturn を記述せず、意図的に 次の case に処理を流すという書き方をする場合もあるでしょう。 これらの場合を単なる記述漏れと区別するために、case 文で break あるいは return を指定しなかった場合は "// break intentionally omitted" (訳注:「意図的に break を省略しました」) というコメントを含めるようにします。

A.4.7. インラインドキュメント

A.4.7.1. ドキュメントの書式

ドキュメントブロック ("docblocks") は、phpDocumentor と互換性のある書式でなければなりません。 phpDocumentor の書式については、このドキュメントの対象範囲外です。 詳細な情報は http://phpdoc.org/ を参照ください。

Zend Framework のために書かれたコード、あるいはフレームワーク上で操作するコードは、 各ファイルの最初に「ファイルレベル」の docblock、 そして各クラスの直前に「クラスレベル」の docblock を含めなければなりません。以下に docblock の例を示します。

A.4.7.2. ファイル

PHP コードを含むすべてのファイルは、最低限これらの phpDocumentor タグを含むヘッダブロックを、 ファイルの先頭に記述しなければなりません。

/**
 * ファイルについての短い説明
 *
 * ファイルについての長い説明 (もしあれば)...
 *
 * LICENSE: ライセンスに関する情報
 *
 * @copyright  2005 Zend Technologies
 * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
 * @version    CVS: $Id:$
 * @link       http://dev.zend.com/package/PackageName
 * @since      File available since Release 1.2.0
*/

A.4.7.3. クラス

各クラスには、最低限これらの phpDocumentor タグを含む docblock が必要です。

/**
 * クラスについての短い説明
 *
 * クラスについての長い説明 (もしあれば)...
 *
 * @copyright  2005 Zend Technologies
 * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://dev.zend.com/package/PackageName
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */

A.4.7.4. 関数

オブジェクトのメソッドを含めたすべての関数には、 最低限以下の内容を含む docblock が必要です。

  • 関数についての説明

  • すべての引数

  • 返り値

"@access" タグは必要ありません。なぜなら、 アクセスレベルについては関数宣言の際の "public"、"private" あるいは "protected" によってわかっているからです。

関数/メソッドが例外をスローする場合には @throws を使用します。

@throws exceptionclass [description]