wiki:EC-CUBE標準規約

Version 25 (modified by Seasoft, 9 years ago) (diff)

core-ml:248 から展開

EC-CUBE標準規約

基本的に  Zend Framework PHP 標準コーディング規約 に順ずる.
以下, 要点及び相違点を規定する.

また, コーディングに際して, 以下のガイドラインに沿うことが望ましい

EC-CUBE標準規約/リファクタリングガイドライン

命名規約

ファイル名

  • 拡張子は, 各ファイル形式に準ずる.
    • PHPファイルは, 必ず .php を使用する.
  • PHPクラスは, 特別な場合を除き, 1クラス1ファイルとし, クラス名.php とする.

PHPクラス名

  • 区切り文字としてはアンダースコア(_)を使用する.
  • クラス名称の先頭には, 大文字でその種類を表す Prefix を付加する.
Prefix種類
SC, GC 1つのサイト内で共有するクラス (他のクラスから呼ばれる)SC_Customer.php
LC 1つのソースファイル内で使用するクラス (通常他のクラスから呼ばれない)LC_Page_Abouts.php
  • クラスがパッケージに属する場合は, Prefix の後にパッケージ名を付加する.
    • Page パッケージでインデックスページとしてアクセスされるクラス名は Index とせず, 属する階層名をクラス名とする.
  • ユーザーが拡張するために extends するクラスは, クラス名の最後に Ex を付加する.

関数名

  • 関数名の先頭には, 小文字でその種類を表す Prefix を付加する.
    • クラス名「LC_*」 (通常他のクラスから呼ばれない)
      • private または protected を意図する場合、Prefix「lf」を省略できる。(Prefix の付加がない場合、「lf」相当とみなす。)
      • public を意図する場合、Prefix「sf」を省略できない。
    • クラス名「SC_*」,「GC_*」 (他のクラスから呼ばれる)
      • public を意図するメソッドの場合、Prefix「sf」を省略できる。(Prefix の付加がない場合、「sf」相当とみなす。)
      • private または protected を意図する場合、Prefix「lf」を省略できない。
  • 名称が複数の単語からなる場合, それぞれの単語の先頭を大文字にする.
  • 関数名は, Prefix + 動詞 + 対象 を原則とする.
Prefix種類
sf 一つのサイト内で共有する関数sfGetProductName()
lf 一つのソースファイル内で使用する関数lfGetProductName()
fn JavaScript で宣言された関数fnGetProductName()

変数名(Smarty 変数も含む)

  • 変数名の先頭には, 小文字でその種類を表す Prefix を付加する.
    • ループ等で一時的に使用する, 数値型の変数には慣習的な $i, $j, $k を使用しても良い.
  • リテラルを格納する (つまり配列・オブジェクト以外の) 変数名は, すべて小文字を使用し, アンダーバーで区切る.
  • 配列・オブジェクトの変数名はキャメルケースを使用する.
Prefix種類
obj クラス変数(オブジェクト)$objQuery
arr 配列$arrCustmers
tpl テンプレート変数(リテラル)$this->tpl_csv_id

定数名

  • すべて大文字で宣言する.
  • 区切り文字としてアンダースコア(_)を使用する.
  • パスに関わるもの(パラメータを含む)は、下記を適用する。(#834 から展開)
    • *_URL: URL
      • 先頭は「スキーム名:」
    • *_URLPATH: URL における url-path 相当 (絶対パス)
      • 先頭は「/」
    • *_HTMLPATH: URL 上の EC-CUBE の /html/ からの相対パス
      • 先頭に「/」を含まない。(/html/ と同一の場合、空文字)
      • 命名に改善余地あり。 (参考: concrete5=DIR_REL) 現在は利用箇所が無いが、今後利用する必要も考えられるので再考していきたい。
    • *_REALFILE: (サーバの)ファイルシステム上のファイルの絶対パス
      • 先頭は「/」
    • *_REALDIR: (サーバの)ファイルシステム上のディレクトリの絶対パス
      • 先頭は「/」。末尾は「/」。
    • *_DIR: 上記に該当しない断片的なディレクトリ情報。
      • 先頭に「/」を含まない。
    • *_FILE: 上記に該当しない断片的なファイル情報。
    • *_PATH: 上記に該当しないもの。上記の複数に該当するもの。

DBテーブル名

  • テーブル名の先頭には, 小文字でその種類を表す Prefix を付加する.
  • 区切り文字としてアンダースコア(_)を使用する.
Prefix種類
mtb マスタデータmtb_pref
dtb データテーブルdtb_order_detail

DBカラム名

  • 特に指定の無い限り, すべて小文字を使用する.
  • 区切り文字としてアンダースコア(_)を使用する.

CSS クラス名

  • 特に定義なし

コーディング規約

HTML

  • ラジオボタン, チェックボックスは <label></label> で囲み, 文字をクリックしてもチェックされるようにする.

PHPコード

  • 改行コードは, 基本的に LF を使用する.
    • 使用する Subversion クライアントによっては, svn add を実行した際に, OS 元来の改行コードがリポジトリに反映されてしまう場合があるため, svn propsetsvn:eol-style=LF を設定しておくのが望ましい.
  • PHPコードの開始タグと, 終了タグは以下のように記述する.
  • 終了タグの後に必ず LF (UNIX の改行コード)を1つ入れる.
  • 余分な空行, 行末の空白は極力削除する.
  • クラス定義, 関数定義の後, 括弧の後で改行する.
  • 80 文字を目安に改行する.
    <?php
    class LC_Page_Abouts {
    
        function process() {
            // some logic.
        }
    }
    

制御文

  • if, for, while, switch 等の制御構造は, 次のルールで開き括弧で記述する.
  • インデントは, 半角スペース4文字を使用し, タブは使用しない.
  • if 文
    <?php
    if ($flag == '1') { // '1' == $flag と書くのは NG
        $ret = 1;
    } elseif ($flag == '2') {
        $ret = 2;
    } else {
        $ret = 3;
    }
    
    • 判定文の対象となる処理結果は先に記述する.
  • for 文
    <?php
    for ($i = 0; $i < $max; $i++) {
        echo $i . "\n";
    }
    
  • foreach 文
    <?php
    foreach ($var as $key => $val) {
        echo $key . ':' . $val . "\n";
    }
    
  • while 文
    <?php
    while ($flag) {
        var_dump($flag);
    }
    
  • do while 文
    <?php
    do {
        var_dump($flag);
    } while ($flag);
    
  • switch 文
    <?php
    switch ($var) {
        case VAR_ONE:
            echo 'one';
            break;
    
        case VAR_TWO:
            echo 'two';
            break;
    
        default:
            echo 'default';
            break;
    }
    
    • case の記述は, 定数を用いるのが望ましい.

文字列

  • 長くなる文字列は分割し, "." で結合する.
    <?php
    $sql = 'SELECT name, age, birthday, zipcode, address, comment '
         . '  FROM user_information '
         . ' WHERE user_id = ? '
         . '   AND is_delete = 0 ';
    
  • ヒアドキュメントを使用しても良い
    <?php
    $sql = <<< __EOS__
        SELECT name,
               age,
               birthday,
               zipcode,
               address,
               comment
          FROM user_information
         WHERE user_id = ?
           AND is_delete = 0
    __EOS__;
    

SQL文

  • フォームから入力された値を利用して SQL文を生成する場合, SQLインジェクションを防ぐため, 必ず PEAR::MDB2 のブレースホルダを利用する.

コメント

  • コメントのコーディングは基本的に  phpDocumentor に準ずる.

ヘッダ

  • 各ファイルのヘッダに著作権表記を記述する.
    <?php
    /*
     * This file is part of EC-CUBE
     *
     * Copyright(c) 2000-2011 LOCKON CO.,LTD. All Rights Reserved.
     *
     * http://www.lockon.co.jp/
     *
     * This program is free software; you can redistribute it and/or
     * modify it under the terms of the GNU General Public License
     * as published by the Free Software Foundation; either version 2
     * of the License, or (at your option) any later version.
     *
     * This program is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     * GNU General Public License for more details.
     *
     * You should have received a copy of the GNU General Public License
     * along with this program; if not, write to the Free Software
     * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
     */
    

クラス定義

  • phpDoc コメントは必要に応じて記述する.
  • @version$Id$ を使用する.
  • メンバ変数は / */ を使用することによって phpDoc コメントとして認識される.
    <?php
    /**
     * クラスの簡単な説明
     *
     * クラスの詳細な説明....
     * ...
     *
     * @package Page
     * @author LOCKON CO.,LTD.
     * @version $Id$
     */
    class LC_Page {
    
        /** メンバ変数 */
        var foo;
    
    }
    

関数定義

  • phpDoc コメントは必要に応じて記述する.
    • @param と @return は必須
  • コード文中にも必要に応じて的確なコメントを記述する.
    <?php
    /**
     * 関数の簡単な説明.
     *
     * 関数の詳細な説明....
     * ....
     *
     * @access private
     * @param string $foo 引数の説明
     * @param string|integer $bar 引数の説明
     * @return string 返り値の説明
     */
    function process($foo, $bar = '') {
        // some process...
        return 'string value';    
    }
    

その他

  • 必要に応じて, 下記のタスクタグを使用しても良い
    • TODO - TODO として残したいコメント
    • FIXME - 必ず修正することを促すコメント
    • XXX - 動くけど怪しい...
      <?php
      // TODO リファクタリングすること.
      
      // FIXME 要修正. バグの説明(#135)
      
      /**
       * :XXX: 以下, 怪しいロジック(#999)
       * 複数行のコメントはこのように.
       *
       * 必要に応じて チケットの ID も記述する.
       */
      
  • コメントによってソースコードが見難くならないように注意する.