2011/01/30

Symfony2 Coding Standards

日本Symfonyユーザ会にて日本語ドキュメントが公開されています。そちらを参考にしてください。
コーディング規約 | Symfony2日本語ドキュメント
http://docs.symfony.gr.jp/symfony2/contributing/code/standards.html
日本語訳(下書き):
Coding Standards — Documentation
http://docs.symfony-reloaded.org/contributing/code/standards.html

コーディング規約

Symfony2 にコードを提供する場合は、以下のコーディング規約に従う必要があります。 手短に言うと、大原則は次の通りです。既存の Symfony2 コードを模倣してね。

構造

  1. ショートタグ (<?) は決して使用しないこと。
    <? // ダメ
    <?php // たとえばこうする
  2. クラスファイルをいつもの終了タグ (?>) で終わらせないこと。
    class MyClass
    {
        ...
    }
    ?> // ダメ
    class MyClass
    {
        ...
    }
    // ?> で閉じない
  3. インデントは 4 つのスペースで行うこと (タブは許可しません)。
    if ('NG') {
    <\t>echo 'タブはダメ、絶対';
    if ('OK') {
        echo '半角スペース 4 つでインデント';
  4. 行の最後はラインフィード (LF; 0x0A) を使うこと。
    if (!strncmp(PHP_OS, 'WIN', 3)) {
        echo 'Windows だと改行コードは \r\n (CRLF) になってるかもっ！';
    if (!strcmp(PHP_OS, 'Linux')) {
        echo 'Linux だと改行コードは \n (LF) になってるはずっ！';
  5. コンマ区切りの後ろにはスペースを 1 つ入れること。
    if ('NG') { // いろいろとダメ
        $arr = array('a','b' ,'c');
        echo 'Hello',' ',  'Symfony2';
    if ('OK') { // こうする
        $arr = array('a', 'b', 'c');
        echo 'Hello', ' ', 'Symfony2';
  6. 開き丸括弧の後ろと閉じ丸括弧の前にスペースを入れないこと。
    if ( 'NG' ) { // ダメ
    if ('OK') {
  7. 演算子 (==、&&、…) の前後にスペースを 1 つ入れること。
    if ( ('NG'||'NG')  &&'NG') { // ダメ
    if (('OK' || 'OK') && 'OK') {
  8. 制御構文 (if、else、for、while、…) の開き丸括弧の前にスペースを 1 つ入れること。
    while(true) {
        if('NG'){
            for  (;;){
                break;
            }
            echo 'だーめ';
        }
        break;
    }
    while (true) {
        if ('OK') {
            for (;;) {
                break;
            }
            echo 'こんなもん';
        }
        break;
    }
  9. return 文の前には空行を入れること。
    function myFunc()
    {
        ...
        return; // 何らかの構文に続けて書かない
    function myFunc()
    {
        if ('OK') {
            return; // 制御構文のすぐ後に return するときは要らない
        }
        ...
     
        return; // 見やすいように空行を 1 つ入れる
  10. 行末にスペースを入れないこと。
    if ('NG') { 
        echo '行末にスペース入ってる';
    if ('OK') {
        echo '行末にスペース入れてない';
  11. 制御構造のボディを明らかにするため、文の数に関係なく波括弧を用いること。
    if ('NG') echo '1 つだけだと';
    else echo '省略されがち';
    if ('OK') {
        echo '1 つでも';
    } else {
        echo '省略しない';
    }
  12. クラス、メソッド、および関数宣言に関する波括弧は単独の行に置くこと。
    class MyClass {
        public function getData()
    {
            return 'NG';
        }
    }
    class MyClass
    {
        public function getData()
        {
            return 'OK';
        }
    }
  13. 条件文と開き波括弧の間にスペースを 1 つ入れ、空行は入れないこと。
    if ('NG'){
        echo 'ダメ';
    } elseif ('NG')
    {
        ...
    }
    if ('OK') {
        echo 'K&R方式';
    } elseif ('OK') {
        ...
    }
  14. クラス、メソッド、プロパティにアクセス修飾子を宣言すること (var の使用は禁止です)。
    // PHP4 のような書き方はダメ
    class MyClass
    {
        var $state;
     
        function getState()
        {
            return $state;
        }
    }
    // PHP5 で！
    class MyClass
    {
        public $state;
     
        public function getState()
        {
            return $state;
        }
    }
  15. PHP のネイティブ型定数 (false, true, null) は小文字を用いること。同じく array() に対しても小文字にすること。
    if (TRUE) {
        $arr = Array();
    if (true) {
        $arr = array();
  16. 定数は大文字を用い、単語間の区切りにアンダースコアを使うこと。
    class MyClass
    {
        const Test_Value = 'NG';
    class MyClass
    {
        const TEST_VALUE = 'OK';
  17. 1 ファイルごとに 1 クラスを定義すること。
    class MyClass1
    {
        ...
    }
     
    class MyClass2
    {
        ...
    }
    // 同じファイル内に複数のクラス定義が存在してはダメ
    // MyClass1 と MyClass2 とでファイルをわける
  18. メソッドの前にクラスプロパティを宣言すること。
    class MyClass
    {
        public function getData()
        ...
     
        public $ng; // メソッドの宣言が始まる前のところに持っていく
    }
    class MyClass
    {
        public $ok;
     
        public function getData()
        ...
    }
  19. 最初に public メソッドを、次に protected メソッドを、最後に private メソッドを宣言すること。
    class MyClass
    {
        protected function proFunc()
        {
        }
     
        private function priFunc()
        {
        }
     
        public function pubFunc()
        {
        }
     // 順番が守られていないっ！
     // public たち → protected たち → private たちのような流れを汲むべし
    class MyClass
    {
        public function pubFunc()
        {
        }
     
        protected function proFunc()
        {
        }
     
        private function priFunc()
        {
        }

命名規則

  1. 変数、関数、およびメソッド名にはアンダースコアを使用しないで、camelCase を用いること。
    class MyClass
    {
        public $left_number;
        public $RightNumber;
     
        public function Add()
     // ごちゃまぜ状態
    class MyClass
    {
        public $leftNumber;
        public $rightNumber;
     
        public function add()
  2. オプション、引数、パラメータ名にはアンダースコアを用いること。
  3. すべてのクラスに名前空間を用いること。
    <?php
    class MyClass
    {
    <?php
     
    namespace Symfony\MySample;
     
    class MyClass
    {
  4. トップレベルの名前空間に Symfony を用いること。
    namespace Ore\MySample;
    namespace Symfony\MySample;
  5. インタフェースの接尾語に Interface を入れること。
    interface Output
    interface OutputInterface
  6. ファイル名に関しては英数字およびアンダースコアを用いること。
    OutputInterface.php

ドキュメント

  1. クラス、メソッド、関数のすべてに PHPDoc ブロックを入れること。
    class MyClass
    {
        public function get($name)
        {
            if (isset($name)) {
                throw new \Exception();
            }
     
            return $name;
        }
    /**
     * 説明用.
     *
     * @author valerian
     */
    class MyClass
    {
        /**
         * 値を取得する.
         *
         * @param string $name 名前
         *
         * @return string 名前を返す
         *
         * @throws \Exception 名前が渡されていない場合
         */
        public function get($name)
        {
            if (isset($name)) {
                throw new \Exception();
            }
     
            return $name;
        }
  2. @package と @subpackage アノテーションは使いません。
    /**
     * 説明用.
     *
     * @package Symfony
     * @subpackage MySample
     * @author valerian
     */
    /**
     * 説明用.
     *
     * @author valerian
     */
訳注:
■命名規則には主に次のような書き方があります。
Pascal形式
先頭を大文字ではじめ、その後は小文字。単語の切れ目は大文字。例：CreateSimpleWindow
camel形式
先頭を小文字ではじめ、その後は小文字。単語の切れ目は大文字。例：createSimpleWindow
アンダースコア区切り
例：create_simple_window、CREATE_SIMPLE_WINDOW
■ソースコードのスタイルには主に次のような流儀があります。
詳細はja.Wikipediaの字下げスタイルで確認してください。
// L&R式
if (a < b) {
    return a;
} else {
    return b;
}
// Microsoft式
if (a < b)
{
    return a;
}
else
{
    return b;
}
// GNU式
if (a < b)
  {
    return a;
  }
else
  {
    return b;
  }
直訳調だとだいぶ意味が伝わりにくいですね…。なので、例を追加することで逃げました
翻訳元:
Fixed google-friendly name (Symfony to Symfony2) - 2010-10-18 06:23:22
https://github.com/symfony/symfony-docs/blob/master/contributing/code/standards.rst
読込中...
投稿者 valerian 時刻: 0:15
ラベル: , ,

0 コメント:

コメントを投稿

登録: コメントの投稿 (Atom)