repo_zf1/documentation/manual/ja/ref/coding_standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 20096 -->
<appendix id="coding-standard">
  <title>Zend Framework PHP 標準コーディング規約</title>
    <sect1 id="coding-standard.overview">
        <title>概要</title>

        <sect2 id="coding-standard.overview.scope">
            <title>対象範囲</title>

            <para>
                このドキュメントは、Zend Framework に貢献してくださる開発者個人 (あるいはチーム)
                のためにコードの書式やドキュメント作成の指針を示すものです。
                Zend Framework を用いて開発をする人たちにとってもこのコーディング規約は有用でしょう。
                これに従えば、Zend Framework のコードとの一貫性が保てるからです。
                そのためには、ここで完全なコーディング規約を示す必要があります。
            </para>

            <note>
                <para>
                    注意: 詳細なレベルまでの設計指針を示すこと以上に、
                    それを標準規格として確立することが大切だと考えています。
                    Zend Framework コーディング規約の指針は、
                    これまで Zend Framework プロジェクトでうまく回っていた方針をまとめたものです。
                    この<ulink url="http://framework.zend.com/license">ライセンス</ulink>のもとで、
                    そのまま使用するなり多少変更して使用するなりすることができます。
                </para>
            </note>

            <para>
                Zend Framework コーディング規約では、次のような内容を扱います。
            </para>

            <itemizedlist>
                <listitem>
                    <para><acronym>PHP</acronym> ファイルの書式</para>
                </listitem>

                <listitem>
                    <para>命名規約</para>
                </listitem>

                <listitem>
                    <para>コーディングスタイル</para>
                </listitem>

                <listitem>
                    <para>インラインドキュメント</para>
                </listitem>
            </itemizedlist>
        </sect2>

        <sect2 id="coding-standard.overview.goals">
            <title>目標</title>

            <para>
                どのような開発プロジェクトであっても、コーディング規約は重要です。
                特に、複数の開発者が参加するプロジェクトならなおさらです。コーディング規約に従うことで、
                コードの品質保持・バグの減少・保守の容易性の確保
                などの助けになります。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.php-file-formatting">
        <title>PHP ファイルの書式</title>

        <sect2 id="coding-standard.php-file-formatting.general">
            <title>全般</title>

            <para>
                <acronym>PHP</acronym> コードのみからなるファイルでは、終了タグ ("?>")
                は決して含めてはいけません。これは必須なものではなく、
                終了タグを省略することで、ファイルの最後にある空白文字が出力に影響することを防ぎます。
            </para>

            <note>
                <para>
                    <emphasis>重要:</emphasis> Zend Framework の <acronym>PHP</acronym>
                    ファイルやそこから派生したものの中では、
                    <methodname>__HALT_COMPILER()</methodname>
                    を使用して任意のバイナリデータを含めることを禁じます。
                    この機能は、インストールスクリプトなどの特別な場合にのみ使用します。
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.indentation">
            <title>字下げ</title>

            <para>字下げは空白 4 文字で行います。タブ文字を使ってはいけません。</para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title>1 行の長さ</title>

            <para>
                1 行の長さを 80 文字までにすることを目指しましょう。すなわち、
                コードの長さを現実的な範囲で 80 文字までにおさめるよう努力すべきです。
                しかしながら、場合によっては少々長くなってしまってもかまいません。
                <acronym>PHP</acronym> コードの行の長さは、最大 120 文字までにするようにしましょう。
            </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.line-termination">
            <title>行末</title>

            <para>
                行末の扱いは、標準的な Unix テキストファイルの方式にあわせます。
                行末は、ラインフィード (LF) のみにしなければなりません。
                この文字のコードは 10、あるいは 16 進形式で 0x0A となります。
            </para>

            <para>
                注意: Apple OS のようなキャリッジリターン (CR) (0x0D) や
                Windows OS のようなキャリッジリターンとラインフィードの組み合わせ (<acronym>CRLF</acronym>)
                (0x0D, 0x0A) を使用しないでください。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title>命名規約</title>

        <sect2 id="coding-standard.naming-conventions.classes">
            <title>クラス</title>

            <para>
                Zend Framework では、クラスの名前が保存先ディレクトリに直接対応するような
                命名規約を採用しています。Zend Framework 標準ライブラリの最上位レベルのディレクトリは
                "Zend/" ディレクトリです。一方、Zend Framework 追加ライブラリの最上位レベルのディレクトリは
                "ZendX/" ディレクトリです。この配下に、すべてのクラスが階層構造で保存されます。
            </para>

            <para>
                クラス名には英数字のみが使用できます。クラス名に数字を使用することは可能ですが、
                ほとんどの場合はお勧めしません。アンダースコアはパス区切り文字としてのみ使用可能です。
                ファイル名が "<filename>Zend/Db/Table.php</filename>" の場合、クラス名を
                "<classname>Zend_Db_Table</classname>" としなければなりません。
            </para>

            <para>
                クラス名が複数の単語から成り立つ場合は、
                それぞれの単語の最初の文字を大文字にしなければなりません。
                大文字を連続して使用することはできません。例えば
                "Zend_PDF" というクラス名は許可されません。代わりに
                "<classname>Zend_Pdf</classname>" を使用します。
            </para>

            <para>
                これらの規約によって、Zend Framework 上で擬似名前空間を定義しています。
                <acronym>PHP</acronym> に名前空間機能が追加されるようになったら、Zend Framework もそれに対応させます。
                それにより、開発者は自分のアプリケーションで名前空間を使用できるようになります。
            </para>

            <para>
                標準ライブラリや追加ライブラリのクラス名を見れば、クラス名の命名規約のよい例となるでしょう。
            </para>

            <note>
                <para>
                    <emphasis>重要:</emphasis> Zend Framework ライブラリとともに配布するが、
                    標準ライブラリや拡張ライブラリではないもの
                    (たとえば、アプリケーションのコードや Zend 以外が作成したライブラリなど)
                    については、"Zend_" や "ZendX_" で始まる名前は使用できません。
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.abstracts">
            <title>抽象クラス</title>

            <para>
                一般に、抽象クラスの規約は通常の <link 
                    linkend="coding-standard.naming-conventions.classes">クラス</link>
                と同じものとなります。追加の規則として、抽象クラスの名前は最後が "Abstract"
                (そしてその前にはアンダースコアはつけない) でなければなりません。
                たとえば <classname>Zend_Controller_Plugin_Abstract</classname>
                は規約にそった名前ではありません。規約に従った名前は
                <classname>Zend_Controller_PluginAbstract</classname> あるいは
                <classname>Zend_Controller_Plugin_PluginAbstract</classname> となります。
            </para>

            <note>
                <para>
                    この命名規約が適用されるのは、Zend Framework 1.9.0 以降です。
                    それより前のバージョンではこの規約に従っていないものもあるかもしれませんが、
                    将来のバージョンでは規約に従うよう名前が変わる予定です。
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.interfaces">
            <title>インターフェイス</title>

            <para>
                一般に、インターフェイスの規約は通常の <link 
                    linkend="coding-standard.naming-conventions.classes">クラス</link>
                と同じものとなります。追加の規則として、インターフェイスの名前の最後は
                "Interface" (そしてその前にはアンダースコアはつけない) にすることもできます。
                たとえば <classname>Zend_Controller_Plugin_Interface</classname>
                は規約にそった名前ではありません。規約に従った名前は
                <classname>Zend_Controller_PluginInterface</classname> あるいは
                <classname>Zend_Controller_Plugin_PluginInterface</classname> となります。
            </para>

            <para>
                この規約は必須ではありませんが、強く推奨します。
                そのファイルがクラスではなくインターフェイスを含むものであることが
                開発者にわかりやすくなるからです。
            </para>

            <note>
                <para>
                    この命名規約が適用されるのは、Zend Framework 1.9.0 以降です。
                    それより前のバージョンではこの規約に従っていないものもあるかもしれませんが、
                    将来のバージョンでは規約に従うよう名前が変わる予定です。
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title>ファイル名</title>

            <para>
                すべてのファイルにおいて、使用可能な文字は英数字・アンダースコア
                およびダッシュ文字 ("-") のみです。空白文字は使用できません。
            </para>

            <para>
                <acronym>PHP</acronym> コードを含むすべてのファイルの拡張子は
                "<filename>.php</filename>" でなければなりません。
                ただしビュースクリプトは例外です。次の例は、Zend Framework
                のクラスに使用できるファイル名を示すものです。
            </para>

            <programlisting language="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></programlisting>

            <para>
                ファイル名は、上で説明したとおりの方式でクラス名と対応していなければなりません。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title>関数およびメソッド</title>

            <para>
                関数名に含めることができるのは英数字のみです。
                アンダースコアを使用してはいけません。
                数字を含めることは可能ですが、ほとんどの場合はお勧めしません。
            </para>

            <para>
                関数名は小文字で始めなければなりません。
                関数名が複数の単語で構成されている場合は、
                各単語の最初の文字を大文字にしなければなりません。
                一般に、このフォーマットは "camelCaps"
                と呼ばれています。
            </para>

            <para>
                関数名は省略しすぎないようにしましょう。
                コードを理解しやすくするため、
                現実的な範囲でできるだけ詳細な名前をつけるようにしましょう。
            </para>

            <para>
                条件を満たす関数名の例を示します。
            </para>

            <programlisting language="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]></programlisting>

            <para>
                オブジェクト指向のプログラミングでは、
                インスタンス変数や静的変数にアクセスするためのメソッドは "get" あるいは "set"
                のいずれかで始めなければなりません。singleton や factory
                などのデザインパターンを使用する場合は、
                メソッド名にパターンの名前を含めるようにしましょう。こうすることで、
                どのパターンを使っているのかがわかりやすくなります。
            </para>

            <para>
                オブジェクト内で "private" あるいは "protected"
                と宣言されているメソッドについては、メソッド名の最初にアンダースコア
                1 文字をつけなければなりません。アンダースコアを使用できるのは、
                この場合のみです。"public" と宣言されているメソッドについては、
                決してアンダースコアで始めてはいけません。
            </para>

            <para>
                グローバル関数は、できる限り使用しないようにしましょう。
                このような関数は、静的クラスにまとめることを推奨します。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.variables">
            <title>変数</title>

            <para>
                変数名に含めることができるのは英数字のみです。
                アンダースコアを使用してはいけません。
                数字を含めることは可能ですが、ほとんどの場合はお勧めしません。
            </para>

            <para>
                クラス内で "private" あるいは "protected"
                と宣言されている変数については、変数名の最初にアンダースコア
                1 文字をつけなければなりません。アンダースコアを使用できるのは、
                この場合のみです。"public" と宣言されている変数については、
                決してアンダースコアで始めてはいけません。
            </para>

            <para>
                関数名と同様 (上の 3.3 を参照ください)、
                変数名も常に小文字で開始する "camelCaps" 方式を使用しなければなりません。
            </para>

            <para>
                変数名は省略しすぎないようにしましょう。現実的な範囲で、
                できるだけ詳細な名前をつけるべきです。"<varname>$i</varname>" や "<varname>$n</varname>"
                のような省略形が許されるのは、小さなループ内で使用する場合のみです。
                ループが 20 行以上のコードになるようなら、
                そのループ変数にはそれなりの名前をつけるべきです。
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.constants">
            <title>定数</title>

            <para>
                定数名には英数字およびアンダースコアを使用できます。
                定数名には数字を使用してもかまいません。
            </para>

            <para>
                定数名は、常にすべて大文字にします。
            </para>

            <para>
                定数名の単語の間はアンダースコアで区切らなければなりません。
                例えば <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> は許されますが、
                <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> は許されません。
            </para>

            <para>
                定数を宣言する際には、クラスのメンバとして "const"
                で定義しなければなりません。"define"
                によるグローバル定数の宣言も可能ですが、お勧めしません。
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title>コーディングスタイル</title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>PHP コードの境界</title>

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

            <programlisting language="php"><![CDATA[
<?php

?>
]]></programlisting>

            <para>
                短いタグは決して使用してはいけません。
                <acronym>PHP</acronym> コードのみからなるファイルでは、終了タグ ("?>")
                は決して含めてはいけません
                (<link linkend="coding-standard.php-file-formatting.general">全般</link> を参照ください)。
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title>文字列</title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>文字列リテラル</title>

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

                <programlisting language="php"><![CDATA[
$a = '文字列の例';
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title>アポストロフィを含む文字列リテラル</title>

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

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` "
     . "WHERE `name`='Fred' OR `name`='Susan'";
]]></programlisting>

                <para>
                    アポストロフィをエスケープするよりも、上の構文のほうが読みやすくなるのでお勧めです。
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.variable-substitution">
                <title>変数の展開</title>

                <para>
                    変数の展開を行うには、次のような方法を使用します。
                </para>

                <programlisting language="php"><![CDATA[
$greeting = "こんにちは $name さん。ようこそ!";

$greeting = "こんにちは {$name} さん。ようこそ!";
]]></programlisting>

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

                <programlisting language="php"><![CDATA[
$greeting = "こんにちは ${name} さん。ようこそ!";
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.string-concatenation">
                <title>文字列の連結</title>

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

                <programlisting language="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></programlisting>

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

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.arrays">
            <title>配列</title>

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title>数値添字の配列</title>

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

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

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

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></programlisting>

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

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
]]></programlisting>

                <para>
                    一方、配列の最初の要素を次の行から始めることもできます。
                    その場合は、配列を宣言した位置からさらに一段インデントした位置で要素をそろえ、
                    それ以降のすべての要素を同じインデントで記述するようにします。
                    閉じ括弧はそれ単体でひとつの行に記述し、インデント量は配列の宣言と同じ位置になります。
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);
]]></programlisting>

                <para>
                    この宣言を使用する際は、配列の最後の要素の後にもカンマをつけておくようにしましょう。
                    そうすることで、配列に新たな要素を追加したときにパースエラーが発生する危険性を
                    少なくできます。
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.arrays.associative">
                <title>連想配列</title>

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

                <programlisting language="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]></programlisting>

                <para>
                    一方、配列の最初の要素を次の行から始めることもできます。
                    その場合は、配列を宣言した位置からさらに一段インデントした位置で要素をそろえ、
                    それ以降のすべての要素を同じインデントで記述するようにします。
                    閉じ括弧はそれ単体でひとつの行に記述し、インデント量は配列の宣言と同じ位置になります。
                    可読性を高めるため、代入演算子 "=>" の位置はそろえておかなければなりません。
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);
]]></programlisting>

                <para>
                    この宣言を使用する際は、配列の最後の要素の後にもカンマをつけておくようにしましょう。
                    そうすることで、配列に新たな要素を追加したときにパースエラーが発生する危険性を
                    少なくできます。
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.classes">
            <title>クラス</title>

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title>クラス宣言</title>

                <para>
                    クラス宣言は、以下の Zend Framework 命名規約に従わなければなりません。
                </para>

                <para>
                    開始波括弧は常にクラス名の下に書かなければなりません。
                </para>

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

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

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

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

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

                <programlisting language="php"><![CDATA[
/**
 * これがドキュメントブロックです
 */
class SampleClass
{
    // クラスのすべての内容は、
    // 空白 4 文字の字下げを使用します。
}
]]></programlisting>

                <para>
                    他のクラスを継承したりインターフェイスを実装したりしているクラスの宣言は、
                    可能な限りその依存関係も同じ行に含めるようにしなければなりません。
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass extends FooAbstract implements BarInterface
{
}
]]></programlisting>

                <para>
                    このように宣言しようとした結果、もし行の長さが <link
                        linkend="coding-standard.php-file-formatting.max-line-length">最大文字数
                        </link> を超えてしまう場合は、キーワード "extends" や "implements"
                    の前で改行してインデント量を一段増やします。
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass 
    extends FooAbstract
    implements BarInterface
{
}
]]></programlisting>

                <para>
                    複数のインターフェイスを実装していて宣言が行の最大長を超える場合は、
                    インターフェイスを区切るカンマの後で改行して
                    インターフェイス名の位置がそろうようにインデントします。
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass 
    implements BarInterface,
               BazInterface
{
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title>クラスのメンバ変数</title>

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

                <para>
                    クラスの内部で使用する変数は、クラスの先頭 (あらゆるメソッド宣言より前)
                    で宣言する必要があります。
                </para>

                <para>
                    <emphasis>var</emphasis> 構文を使ってはいけません。メンバ変数を宣言する際には
                    <property>private</property>、<property>protected</property> あるいは <property>public</property>
                    のいずれかの修飾子を用いてアクセス範囲を指定します。
                    メンバ変数を public 宣言して外部からアクセスさせることもできますが、
                    それよりはアクセサメソッド (set &amp; get) を使用する方式のほうを推奨します。
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title>関数およびメソッド</title>

            <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
                <title>関数およびメソッドの宣言</title>

                <para>
                    関数は、以下の Zend Framework 関数命名規約に従わなければなりません。
                </para>

                <para>
                    クラス内でメソッドを宣言する際には、常に
                    <property>private</property>、<property>protected</property> あるいは
                    <property>public</property> のいずれかの修飾子を用いてアクセス範囲を指定しなければなりません。
                </para>

                <para>
                    クラスと同様、波括弧は関数名の次の行に書かなければなりません。

                    関数名と引数定義用の開始括弧の間にはスペースを入れてはいけません。
                </para>

                <para>
                    グローバルスコープの関数は、できるだけ使わないようにしましょう。
                </para>

                <para>
                    クラス内の関数宣言の例として適切なものを次に示します。
                </para>

                <programlisting language="php"><![CDATA[
/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar()
    {
        // 関数のすべての内容は、
        // 空白 4 文字の字下げを使用します。
    }
}
]]></programlisting>

                <para>
                    引数リストが <link 
                        linkend="coding-standard.php-file-formatting.max-line-length">行の最大文字数
                        </link> を超える場合は改行できます。
                    関数やメソッドの引数を改行して続ける場合は、
                    その宣言部よりさらに一段インデントしなければなりません。
                    そして、閉じ括弧の前にさらに改行を入れます。
                    宣言部の閉じ括弧と本体の開始波括弧はスペースをひとつはさんで同じ行に記述し、
                    そのインデント量は関数やメソッドの宣言位置と同じになります。
                    そんな場合の例を次に示します。
                </para>

                <programlisting language="php"><![CDATA[
/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // 関数のすべての内容は、
        // 空白 4 文字の字下げを使用します。
    }
}
]]></programlisting>

                <note>
                    <para>
                        <emphasis>注意:</emphasis> 値の参照渡しは、
                        メソッドの宣言時にパラメータを渡す部分においてのみ可能です。
                    </para>
                </note>

                <programlisting language="php"><![CDATA[
/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar(&$baz)
    {}
}
]]></programlisting>

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

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

                <programlisting language="php"><![CDATA[
/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * 間違いです
     */
    public function bar()
    {
        return($this->bar);
    }

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

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title>関数およびメソッドの使用法</title>

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

                <programlisting language="php"><![CDATA[
threeArguments(1, 2, 3);
]]></programlisting>

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

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

                <programlisting language="php"><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

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

threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title>制御構造</title>

            <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
                <title>If/Else/Elseif</title>

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

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

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

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]></programlisting>

                <para>
                    条件文が <link
                        linkend="coding-standard.php-file-formatting.max-line-length">行の最大文字数
                        </link> を超え、さらに複数の条件がある場合は、
                    それらを複数行にわけて記述できます。その場合は論理演算子の前で改行し、
                    条件句の最初の文字がそろうように位置を合わせます。
                    条件部の閉じ括弧と本体の開始波括弧はスペースをひとつはさんで同じ行に記述し、
                    そのインデント量は制御構文の開始位置と同じになります。
                </para>

                <programlisting language="php"><![CDATA[
if (($a == $b) 
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}
]]></programlisting>
                
                <para>
                    後者の記法の意図は、
                    後から条件句を追加したり削除したりしたときに問題が起こりにくくすることにあります。
                </para>

                <para>
                    "elseif" あるいは "else" を含む "if" 文の場合の決まりは、通常の "if" と同じです。
                    次の例は、"if" 文に "else" や "elseif" が含まれる場合のものです。
                </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}

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

if (($a == $b) 
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}
]]></programlisting>

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

            <sect3 id="coding-standards.coding-style.control-statements.switch">
                <title>Switch</title>

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

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

                <programlisting language="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
]]></programlisting>

                <para>
                    <property>switch</property> 文の <property>default</property> は、
                    決して省略してはいけません。
                </para>

                <note>
                    <para>
                        <emphasis>注意:</emphasis> 各 <property>case</property> の最後に
                        <property>break</property> や <property>return</property> を記述せず、意図的に
                        次の <property>case</property> に処理を流すという書き方をする場合もあるでしょう。
                        これらの場合を単なる記述漏れと区別するために、<property>case</property> 文で
                        <property>break</property> あるいは <property>return</property> を指定しなかった場合は
                        「意図的に break を省略した」というコメントを含めるようにします。
                    </para>
                </note>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title>インラインドキュメント</title>

            <sect3 id="coding-standards.inline-documentation.documentation-format">
                <title>ドキュメントの書式</title>

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

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

            <sect3 id="coding-standards.inline-documentation.files">
                <title>ファイル</title>

                <para>
                    <acronym>PHP</acronym> コードを含むすべてのファイルは、最低限これらの
                    phpDocumentor タグを含むドキュメントブロックを、
                    ファイルの先頭に記述しなければなりません。
                </para>

                <programlisting language="php"><![CDATA[
/**
 * ファイルについての短い説明
 *
 * ファイルについての長い説明 (もしあれば)...
 *
 * LICENSE: ライセンスに関する情報
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/
]]></programlisting>

                <para>
                    <property>@category</property> アノテーションの値は "Zend" でなければなりません。
                </para>

                <para>
                    <property>@package</property> アノテーションも必須で、
                    ファイルに含まれるクラスのコンポーネント名と同じでなければなりません。
                    一般的には、これは "Zend" プレフィックスとコンポーネント名のふたつの部分からなります。
                </para>

                <para>
                    <property>@subpackage</property> アノテーションはオプションです。
                    指定する場合は、サブコンポーネント名からクラスのプレフィックスを除いたものとしなければなりません。
                    上の例の場合は、ファイルに含まれるクラス名が "<classname>Zend_Magic_Wand</classname>" であるか、
                    そのクラス名をプレフィックスの一部として使っているのでしょう。
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.classes">
                <title>クラス</title>

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

                <programlisting language="php"><![CDATA[
/**
 * クラスについての短い説明
 *
 * クラスについての長い説明 (もしあれば)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */
]]></programlisting>

                <para>
                    <property>@category</property> アノテーションの値は "Zend" でなければなりません。
                </para>

                <para>
                    <property>@package</property> アノテーションも必須で、
                    そのクラスが属するコンポーネントの名前と同じでなければなりません。
                    一般的には、これは "Zend" プレフィックスとコンポーネント名のふたつの部分からなります。
                </para>

                <para>
                    <property>@subpackage</property> アノテーションはオプションです。
                    指定する場合は、サブコンポーネント名からクラスのプレフィックスを除いたものとしなければなりません。
                    上の例の場合は、ファイルに含まれるクラス名が "<classname>Zend_Magic_Wand</classname>" であるか、
                    そのクラス名をプレフィックスの一部として使っているのでしょう。
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.functions">
                <title>関数</title>

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

                <itemizedlist>
                    <listitem><para>関数についての説明</para></listitem>
                    <listitem><para>すべての引数</para></listitem>
                    <listitem><para>返り値</para></listitem>
                </itemizedlist>

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

                <para>
                    関数/メソッドが例外をスローする場合には、すべての既知の例外クラスに対して
                    @throws を使用します。
                </para>

                <programlisting language="php"><![CDATA[
@throws exceptionclass [description]
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>

</appendix>
<!--
vim:se ts=4 sw=4 et:
-->