php關於編碼規範的文檔(收藏)

黄舟
發布: 2023-03-14 09:44:01
原創
1785 人瀏覽過

  為了提高工作效率,確保開發的有效性和合理性,並最大程度提高程式碼的可讀性和可重複利用性,提高溝通效率,需要一份程式碼編寫規格。讓大家養成良好的程式碼編寫習慣,同時減少程式碼中的bug。
      CleverCode整理了一些規格。本規範包含PHP開發時程式編碼中命名規範、程式碼縮排規則、控制結構、函數呼叫、函數定義、註解、包含程式碼、PHP標記、常最命名等方面的規則。

1 文件格式

1.1 文件標記

所有PHP文件,其程式碼標記均使用完整PHP標籤,不建議使用短標籤,例如:

<?php  
//推荐  
echo &#39;hello world&#39;;  
?>  
  
  
<?  
//短标签格式不推荐  
echo &#39; hello world &#39;;  
?>
登入後複製

1) 使用短標籤格式容易和XML混淆,並且不是所有PHP版本和伺服器都預設支援或開啟短標籤選項(從PHP5.4開始,php.ini中的短標籤選項不影響短標籤的使用) 。對於只含有PHP代碼的文件,將在文件結尾處忽略?>。這是為了防止多餘空格或其他字元影響到代碼。
2)其實這個問題只有在不開啟壓縮或快取輸出時才會出現,例如:
php.ini-禁止壓縮輸出及快取輸出

zlib.output_conpression = off
output_buffering = off
登入後複製

foo.php ,注意這個時候有一些空格或換行符掉在了之後,當然這在頁面上是看不
到的。

<?php  
    $foo= &#39;foo&#39;;  
?>
登入後複製

index.php,在包含foo.php的同時,其實已經輸出一些空格或換行了。

<?php  
    include &#39;foo.php&#39;;  
    session_start();  
?>
登入後複製

這時將會看到一個警告(warning):「...Cannotsendsessioncachelimiter-headersalreadysent...」

1.2 檔案和目錄命名

程式檔案名稱和目錄名稱均採用有意義的英文命名,不使用拼音或無意義的字母,只允許出現字母、數字、下畫線和中畫線字符,同時必須以“.php”結尾(模板文件除外)。
//類別統一採用
DemoTest.php

2 命名規範

2.1 變數命名

PHP中的變數以一個美元符號後面跟變數名表示。變數名區分大小寫。一個有效變景名由字母或下畫線開頭,後面跟著任意數量的字母、數字、下畫線。正常的正規表示式將表述為:[a-zA-Z_\x7f-\xff][a-zA-ZO-9_'x7f-\xff],不應該在變數中使用中文等非ASCII字元。

2.1.1 程式整體

程式整體以駝峰法命名,以小寫字母開始,同時命名要有意義,如:

function displayName($name){  
    echo $name;  
}
登入後複製

2.1.2 PHP全域變量鍵值

PHP全域變數鍵值兩邊都有中間使用駝峰法命名。

2.1.3 普通變數

普通變數整體採用駝峰法,
依約定命名,並避免使用常用關鍵字或存在模糊意義的單字。變數應該以名詞為主。
字串:$myName
陣列:$myArray

不建議:
$yes:不應該使用其作為bool型變童,因為變數很可能被改變,其可能使得Syeszflase,而讓其程式碼邏輯變得混亂。
$sex:具有模糊意義且不地道的英文單詞,性別的命名應該是$gender。

2.1.4 函數名稱

函數名稱既要有意義,一看就知道要幹什麼,也要盡量縮寫。建議採用動詞或動詞加上形容詞
的命名方式,如showMsg。不建議下面這樣的函數名稱:

getPublishedAdvertisementBy
CategoryAndCategoryldAndPosition()
登入後複製

上面的函數名稱可以提煉為:

getAd($category,$categoryid,$position,$published)
登入後複製

例如1)類別公共函數:

public function doGetUserName($job)
登入後複製

例如2)類別私有函數,以「_」開頭:

private function _doGetUserName($job)
登入後複製


例如3)類別保護函數,以「_」開頭:

protected function _doGetUserName($job)
登入後複製

2.1.5 類中的屬性

類別中的變數遵守普通變數的命名規則。
例如1)公共屬性,static屬性:

public $userName = ’CleverCode’;
static $userType = array(1,2,3);
登入後複製

例如2)私有屬性,以「_」開頭:

private $_userName = ’CleverCode’;
登入後複製

例如3)保護屬性,以「_」開頭:

protected $_userName = ’CleverCode’;
登入後複製

例如4)常數,全部大寫,以「_」分隔:

const TYPE_GZ = 4;
登入後複製

2.2 資料庫命名

2.2 .1 庫命名

1)使用小寫字母。 (windows不區分大小寫,linux區分大小寫,為了庫移植相容,所以全部小寫)
2)多個單字組成,單字之間用"_"分隔。
例如:

db_user,db_system。
登入後複製

2.2.2 表命名

1)表名皆使用小寫字母。
2)表名字使用統一的前綴,前綴不能為空(模組化,可有效規避MYSQL保留字)。
3)對於多個單字組成的表名,使用"_"間隔。
例如:

pre_users,pre_user_shop
登入後複製

2.2.3 表格欄位命名

1)全部使用小写字母命名。
2)多个单词不用下画线进行分割(重要)。
3)如果有必要,给常用字段加上表名首字母作为前缀。
4)避免使用关键字和保留字,但约定俗成的除外。
例如:

username,newsid,userid,logid
登入後複製

3 注释规范

3.1 文件注释

文件注释通常放在整个PHP文件头部,其内容包括文件版权、作者、编写日期、版本号等
重要信息。PHP中,可以参照phpdocument规范,便于利用程序自动生成文档。
文件注释遵循以下规则:
1)必须包含本程序的描述;
2)必须包含作者;
3)必须包含版权;
4)必须包含文件的名称;
5)可以包含书写日期;
6)可以包含版本信息;
7)可以包含重要的使用说明,如类的调用方法、注意事项等。
例如:

<?php  
  
  
/**  
 * SystemUser.php  
 *   
 * 系统用户操作操作  
 *  
 * Copyright (c) 2015 http://blog.csdn.net/CleverCode  
 *  
 * modification history:  
 * --------------------  
 * 2015/5/11, by Clever Code, Create  
 *
登入後複製

3.2 类与接口注释

类和接口的注释应该尽量简洁。按照一般的习惯,一个文件只包含一个类,在类注释中通常不需要再加上作者和版本等信息,加上可见性和简中的描述即可。如果文件注释已经足够详细,可以不用给类写注释。如果同时存在接口和接口的实现类,通常做法是仅在接口中进行注释。

3.3 方法和函数注释

方法和函数的注释写在前面,通常需要标明的信息主要是可见性、参数类型和返回值的类
例如1:

/** 
  * 对比新旧数据 
  * 
  * @param bigint $userid 人编号 
  * @param array $oldMap 旧数据 
  * @param array $newMap 新数据(输出参数) 
  * @return string 成功返回&#39;OK&#39;,失败返回错误信息 
  */  
 public static function diffRecommendInfo($userid, $oldMap, &$newMap){  
 }
登入後複製

例如2:

/** 
  * 插入日志数据 
  * 
  * @param bigint $data[‘userid’] 用户编号 
  * @param array $data[‘logintime’] 登录时间 
  * @return string 成功返回&#39;OK&#39;,失败返回错误信息 
  */  
 public static function insertLogData($data){  
 }
登入後複製

3.4 Action注释

由于我们都是使用的zend开发模式,在Action是http请求处理逻辑的入口,那么必然会传递get,post等参数。可以注释如下.
例如1)没有get,post传递参数时候:

/** 
     * 自动设置名称 
     * 
     * @return void 
     */  
    public function autosetAction(){  
}
登入後複製

例如2 )有get传递参数时候:

/** 
     * 获取用户名称 
     * 
     * @get int $userid 用户编号 
     * @get int $currpage 当前页 
     * @get int $pagesize 
     * 
     * @return void 
     */  
public function getusernameAction(){  
}
登入後複製

例如3) 有post传递参数时候:

/** 
     * 删除用户 
     * 
     * @post int $userid 用户编号 
     * @return void 
     */  
public function deleteuserAction(){  
}
登入後複製

3.5 单行注释

1)写在被注释代码前面,而不是后面。但对于单行语句,按照习惯可以把注释放在语句末尾,也可以写在行上面。
2)对于大段注释,使用/**/格式,通常在文件和函数注释中使用,而代码内部统一使用//注释,因为其写起来简单。
例如:
//姓名

$name = ’CleverCode’;

4 代码风格

4.1 缩进与空格

在书写代码的时候,必须注意代码的缩进规则:
1)使用4个空格作为缩进,而不使用tab缩进(如在UltraEdit中可以进行预先设置)。
2)变量赋值时,等号左右留出空格。
例如:
$name = 'CleverCode';//推荐
$name='CleverCode';//不推荐

为了最大程度减轻工作量,保持代码美观,建议使用大型IDE管理代码。比如,在zend studio中,使用Ctrl+Shift+F组合键对代码进行格式化。

4.2 语句断行

代码书写中应遵循以下原则:
1)尽量保证程序语句一行就是一句;
2)尽量不要使一行的代码太长,一般控制在80个字符以内;
如果一行代码太长,请使用类似.=的方式断行书写;
执行数据库的SQL语句操作时,尽量不要在函数内写SQL语句,而先用变量定义SQL
语句,然后在执行操作的函数中调用定义的变量。
例如:

//代码分割
$sql= "SELECTusername,password,address,age,postcode from test_t";
$sql.= "WHEREusername=${user}";
$ret = mysql_query($sql);
登入後複製

3)一个函数控制在200行以内;
4)if最多嵌套3层;
//不推荐

If(){  
    If(){  
        If(){  
            If(){  
                ……  
            }  
        }  
    }  
}
登入後複製

5)循环最多3层。

//不推荐  
For(){  
    For(){  
        For(){  
            For(){  
                ……  
            }  
        }  
    }  
}
登入後複製

6)if或者for语句块中只有一行时候,加上{}。当有语句变动的时候会带来不必要的bug。

//推荐  
If($a == 1){  
    echo 1;  
}  
  
//不推荐  
If($a == 1) echo 1;
登入後複製

4.3 空行

1)函数与函数之间空行。
2)同一个函数不同逻辑块之间空行,查阅不同的逻辑块条理更清晰。


4.4 函数结构

通常一个函数分为三部分。第一部分:检查参数;第二部分:处理逻辑;第三部分:返回结果。
例如:

/** 
 * 删除日志通过uid 
 * 
 * @param string $uid 用户uid 
 * @return string 成功返回&#39;OK&#39;,失败返回错误信息 
 */  
public static function deleteLogByUid($uid){  
  
  
    //第一步:检查参数。防止处理部分异常;比如$uid是传入array();  
    if (!is_numeric($uid)) {  
        return &#39;!is_numeric($uid)&#39;;  
    }  
      
    //第二步:处理逻辑。  
    $affected = $userLogTable->delete(&#39;where userid = &#39; . $uid);  
      
    //第三步:返回结果。让调用者知道是否处理正常。  
    if($affected){  
        return &#39;OK&#39;;  
    }  
      
    return &#39;delete error!&#39;;  
}
登入後複製

4.5 函数返回函数

需要客户端的函数:
返回值

$ret = array(‘code’=> 1 ,msg=>’’,data => array());
登入後複製

4.6 更好的习惯

在代码中,使用下面列举的写法,可以使代码更优雅。
1)多使用PHP中已经存在的常量,而不要自己定义,例如:

echo$meg."\r\n";
echo$msg,PHPJEOL;
登入後複製

PHP中,PHP_EOL是一个预定义常量,表示一行结束,随着所使用系统的不同,使用PHP_EOL会让代码更具有可移植性。

2)更详尽的注释。
注释是一门艺术,好的注释可以比代码更精彩。不用担心效率问题。一则注释对代码的效
率影响不大,其次在正式产品中可以对代码中的注释进行批量删除。注释做到极致和完美的典型代表是Apache组织各种产品的源代码。

3)不要滥用语法糖。
语法糖也就是语言中的潜规则,即不具有普遍代表性的语法。少量使用语法糖会尝到甜
头,大量使用则是一种灾难。
例如以下代码,可读性比较差;

$a?$a-$b:3&&$c&&$d=1;
登入後複製

以上是php關於編碼規範的文檔(收藏)的詳細內容。更多資訊請關注PHP中文網其他相關文章!

相關標籤:
來源:php.cn
本網站聲明
本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn
熱門教學
更多>
最新下載
更多>
網站特效
網站源碼
網站素材
前端模板