一、 編碼規約 1.1 標簽 (1)【強制】PHP 程式可以使用或來界定 PHP 代碼,在 HTML 頁面中嵌入純變數時,可以使用這樣的形式,不可使用其他的標簽變種。 正例: <?php /** * 編碼規約 * Created by PhpStorm. * User: [email protected] ...
一、 編碼規約
1.1 標簽
(1)【強制】PHP 程式可以使用或來界定 PHP 代碼,在 HTML 頁面中嵌入純變數時,可以使用這樣的形式,不可使用其他的標簽變種。
正例:
<?php
/**
* 編碼規約
* Created by PhpStorm.
* User: [email protected]
* Date: 2022/03/01 16:05
* Description:
*/
$param1 = 'Hello World!';
?>
<html>
<title>測試</title>
<body>
<div><?php echo $param1?></div>
<div><?=$param1?></div>
</body>
</html>
(2)【強制】純 PHP 類文件,文件最後一個?>省略。
正例:
<?php
/**
* 純php文件
* Created by PhpStorm.
* User: [email protected]
* Date: 2022/03/01 17:15
* Description:
*/
class RuleController
{
public function __construct()
{
echo "Hello World!";
}
}
1.2 編碼
(1)【強制】PHP 代碼必須只使用不帶 BOM 的 UTF-8。
1.3 註釋
對於註釋的要求:第一、能夠準確反應設計思想和代碼邏輯;第二、能夠描述業務含義,使別的程式員能夠迅速瞭解到代碼背後的信息。完全沒有註釋的大段代碼對於閱讀者形同天書,註釋是給自己看的,即使隔很長時間,也能清晰理解當時的思路;註釋也是給繼任者看的,使其能夠快速接替自己的工作。
好的命名、代碼結構是自解釋的,註釋力求精簡準確、表達到位。避免出現註釋的 一個極端:過多過濫的註釋,代碼的邏輯一旦修改,修改註釋是相當大的負擔。
所有多行註釋都必須帶有author和date兩個屬性。
1)單行註釋:在語句結尾用雙反斜杠“//”註釋
2)多行註釋:多行註視以“/*”或“/**”符號開頭,以“*/”符號作為註釋結束符。
需要生成文檔的註釋必須是以“/**”開頭,以“*/”結尾。主流的 IDE 開發工具(如 Eclipse,PHPStorm等)會用不同的顏色來區分下麵的幾種註釋。
1.3.1 文件註釋
(1)【推薦】生成文件時,在文件頭部處,需要添加文件描述、創建者和創建時間的多行註釋,以/**開頭,以*/結尾。
正例:
<?php
/**
* 編碼規約【文件描述】
* Created by PhpStorm.
* User: [email protected]【創建者】
* Date: 2022/03/01 16:05【創建時間】
* Description:
*/
1.3.2 類註釋
(1)【強制】生成類時,在文件頭部處,需要添加類描述、創建者(@author)、創建時間(@date)以及類屬性(@property)的多行註釋,以/**開頭,以*/結尾。
正例:
/**
* 類概要描述
* 類詳細的描述
*
* @author [email protected]【創建者】
* @date 2022-03-04【創建時間】
*
* @property integer $id 認證ID【屬性類型+變數名+描述】
* @property integer $userId 用戶ID【屬性類型+變數名+描述】
*/
class TestController
{}
1.3.3 方法註釋
(1)【強制】新建方法時,在方法申明頭部處,需要添加方法描述、創建者(@author)、創建時間(@date)、參數(@param 類型、變數名、描述、可能的值)及返回結果(@return 類型、變數名、描述、可能的值)的多行註釋,以/**開頭,以*/結尾。
正例:
/**
* 方法描述
* @author [email protected]【創建者】
* @date 2022-02-08【創建時間】
* @param array $params 參數1【參數類型+參數名+參數描述,如果是多層結構,需要將基礎結構和對應的欄位寫出來】
* array(
* "medal_id" => array(),//勛章ID數組
* "user_id" => array(),//用戶ID數組
* )
* @param int $userId 用戶ID
* @return array $return 返回結果【需要返回結果的基礎結構和對應的欄位描述寫出來】
* array(
* "ret" => "0",//錯誤碼,0是成功,其他失敗
* "reason" => "success",//錯誤描述
* "data" => array(
* "user_id" => "用戶ID",
* ....
* )
* )
*/
public static function run($params, $userId)
{
$return = [
'ret' => 0,
'reason' =>'success',
'data' => []
];
return $return;
}
1.3.4 屬性註釋
(1)【推薦】新建類屬性時,在屬性申明頭部處,需要屬性描述(@var 類型、變數名、描述、可能的值)的多行註釋,以/**開頭,以*/結尾。
正例:
/**
* @var int $public 公共屬性
*/
public $public = 0;
/**
* @var string $private 私有屬性
*/
private $private = "";
1.3.5 方法內部註釋
(1)【強制】方法內部單行註釋,在被註釋語句上方另起一行,使用//註釋。方法內部多行註釋使用/* */註釋,註意與代碼對齊。
正例:
//這是單行註釋
$test = 1;
/*
* 這是多行註釋
*/
$rule = 2; //這是單行註釋
//邏輯有錯,修改 by [email protected] 2022-03-01
$url = 1;
1.3.6 其它
1、【推薦】待辦事宜(TODO):( 標記人,標記時間,[預計處理時間])
表示需要實現,但目前還未實現的功能,但已經被廣泛使用。只能應用於類,介面和方法。
正例:
//TODO 待處理邏輯,需要及時處理消除邏輯 by [email protected] 2022-03-04
2、【強制】錯誤,不能工作(FIXME):(標記人,標記時間,[預計處理時間])
在註釋中用 FIXME 標記某代碼是錯誤的,而且不能工作,需要及時糾正的情況。
正例:
//FIXME 標記修複錯誤代碼 by [email protected] 2022-03-04
3、【強制】謹慎註釋掉代碼。在上方詳細說明,而不是簡單地註釋掉。如果無用,則刪除。說明:代碼被註釋掉有兩種可能性:1)後續會恢復此段代碼邏輯。2)永久不用。前者如果沒有備註信息,難以知曉註釋動機。後者建議直接刪掉(代碼倉庫保存了歷史代碼)。
正例:
/*
臨時註釋代碼後續用於恢復
如果永久不適用,直接刪掉 by [email protected] 2022-03-04
$a = 1;
$b = 2;
*/
$a = 2;
$b = 3;
$c = $a + $b;
反例:
$a = 2;
$b = 3;
// $c = $a + $b;
$d = $a - $b;
echo $d;
4、【強制】代碼修改的同時,註釋也要進行相應的修改,尤其是參數、返回值、異常、核心邏輯等的修改。
說明:代碼與註釋更新不同步,就像路網與導航軟體更新不同步一樣,如果導航軟體嚴重滯後,就失去了導航的意義。
5、【強制】所有的枚舉類型欄位必須要有註釋,說明每個數據項的用途。
正例:
const STATUS_ON = 1;//啟用
const STATUS_OFF = 0;//禁用
const LEVEL1 = 1;//等級1
const LEVEL2 = 2;//等級2
const LEVEL3 = 3;//等級3
const LEVEL4 = 4;//等級4
const LEVEL5 = 5;//等級5
const LEVEL6 = 6;//等級6
const LEVEL7 = 7;//等級7
反例:
const LEVEL1 = 1;
const LEVEL2 = 2;
const LEVEL3 = 3;
const LEVEL4 = 4;
const LEVEL5 = 5;
const LEVEL6 = 6;
const LEVEL7 = 7;
1.4 命名規則
Pascal命名法:所有單詞第一個字母大寫,其他字母小寫。
Camel命名法(駝峰命名法) :除了第一個單詞,所有單詞第一個字母大寫,其他字母小寫。
1)【強制】採用英文單詞或其組合,便於記憶和閱讀,切忌使用漢語拼音來命名;
正例:validCateMedalList(有效分類勛章列表)
反例:yxflxz
2)【強制】杜絕完全不規範的縮寫,避免望文不知義;此類隨意縮寫嚴重降低了代碼的可閱讀性;
正例:AbstractClass condition
反例:AbsClass condi
3)【強制】為了達到代碼自解釋的目標,任何自定義編程元素在命名時,使用儘量完整的單片語合來表達其意,不要嫌名字長;
正例:haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表)
反例:list
4)【強制】代碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。
正例:haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表)
反例:dlxzjdList 中文
說明:正確的英文拼寫和語法可以讓閱讀者易於理解,避免歧義。註意,即使純拼音命名方式也要避免採用。
1.4.1 文件
1)【強制】類文件的名稱和類名一致;
正例:HelloWorld.php(文件名)=> HelloWorld(類名)
反例:Hello.php(文件名)=> HelloWorld(類名)
2)【推薦】配置文件名小寫,多個單詞用-分割開;
正例:config.php config-prod.php
反例:Config.php configProd.php
3)【推薦】嵌套 php 的 view 文件使用小寫,多個單詞用-分隔開;
正例:add-app.php
反例:addApp.php
1.4.2 類
類命名採用 Pascal 命名方法,類名應該和文件名相匹配,如HelloWorld;
正例:HelloWorld
反例:helloWorld helloworld hello-world hello_world
1.4.3 函數/方法
1)【強制】通常方法一般為一個動作或行為動詞,函數/方法的命名採用 Camel命名方法;
正例:runAction()
反例:RunAction() run-action() run_action()
2)【強制】儘量用有意義,描述性的詞語來命名;
正例:checkForErrors() dumpDataToFile() getUserList()
反例:errorCheck() dataFile() user()
3)【強制】有時首碼名是有用的:
is - 含義為問一個關於某樣事物的問題。無論何時,當人們看到 is 就會知道這是一個問題。
get - 含義為取得一個數值。
set - 含義為設定一個數值
update–含義為更新數據
insert/add/save–含義為插入數據
remove/delete–含義為刪除數據
count – 含義為計算總數
list – 含義為獲取多個對象列表
例如:isHitRetryLimit
正例:isHitRetryLimit() updateUserInfo() getUserInfo() insertUser() countStatusOnUser() listUser() getUserList()
反例:retryLimit() userInfo() userList() statusOn()
4)【推薦】內部成員函數命名應該是以 “_”開始;
正例:function _isUserTicket()
1.4.4 變數名
1)【強制】命名採用 Camel命名方法;
正例:userListuserList userListtestData
反例:user−listuser-list user−listuser_list $UserList
2)【強制】用有意義的,描述性的詞語來命名變數;
正例:$haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表)
反例:$list
3)【強制】別用縮寫。用 name, address, salary 等代替nam, addr, sal,全局變數以”g_”開頭;
正例:haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表)haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表) haveLightNextLevelMedalProgressValueList(已點亮下級勛章進度列表)g_user
反例:$dlxzmedlprosList 中文
4)【強制】別使用單個字母的變數象 i, n, x 等. 使用 index, temp 等 ,用於迴圈迭代的變數;
正例:for (index=0;index = 0; index=0;index < count;count; count;index++) {... }
反例:for (i=0;i = 0; i=0;i < count;count; count;i++) {... }
1.4.5 常量名
常量命名全部大寫,單詞間用下劃線隔開,力求語義表達完整清楚,不允許出現小寫字母,不要嫌名字長。
正例:MAX_STOCK_COUNT
反例:MAX_COUNT
1.5 書寫規則
1.5.1 文件
1)【強制】所有的 PHP 文件必須使用 Unix LF(換行)作為行結束符。
2)【強制】所有 PHP 文件必須以一個空行結束。
3)【強制】純 PHP 代碼的文件關閉標簽?>必須省略
1.5.2 行
1)【推薦】行長度不可有硬限制。
2)【推薦】軟性的長度約束限制在120個字元以內,若超過此長度,帶代碼規範檢查的編輯器要發出警告,不過一定不可發出錯誤提示。
4)【推薦】空行可以用來改善可讀性和區分相關的代碼塊。
正例:
//第一段代碼
if ($a = 1) {
$a = 1;
$b = 2;
echo 3;
}
//第二段代碼
$d = 1;
$c = 2;
echo $d + $c;
5)【強制】一行不應多於一個語句。
正例:
if ($a = 1) {
$a = 1;
$b = 2;
echo 3;
}
反例:
if ($a = 1) {$a = 1; $b = 2; echo 3;}
1.5.3 縮進
每個縮進的單位約定是4個空格的縮進,並且不可使用製表符作為縮進,需每個參與項目的開發人員在編輯器(Eclipse、EditPlus、Zend Studio、PhpStorm 等)中進行強制設定將 TAB 轉化為 4 個空格,以防在編寫代碼時遺忘而造成格式上的不規範。
1.5.4 命名空間
1)【強制】namespace聲明之後必須存在一個空行。
2)【強制】所有的use聲明必須位於namespace聲明之後。
3)【強制】每條use聲明必須只有一個use關鍵字。
4)【強制】use語句塊之後必須存在一個空行
正例:(涉及1-4點)
namespace backend\controllers;
use backend\model\BaseBackendController;
class ClassWorkController extends BaseBackendController
{
}
反例:(涉及1-4點)
namespace backend\controllers;
use backend\model\BaseBackendController;
class ClassWorkController extends BaseBackendController
{
}
1.5.5 控制結構
對於控制結構的樣式規則概括如下:
1)【強制】控制結構關鍵詞(if/elseif/else/switch/case/while/for/foreach/try/catch)之後必須有一個空格
2)【強制】左括弧之後不可有空格
3)【強制】右括弧之前不可有空格
4)【強制】在右括弧和左花括弧之間必須有一個空格
5)【強制】代碼主體必須有一次縮進
6)【強制】右花括弧必須主體的下一行
7)【強制】每個結構的主體必須被括在花括弧里。這結構看上去更標準化,並且當加新行的時候可以減少引入錯誤的可能性。
正例:(涉及1-7點)
public static function main() {
// 縮進 4 個空格 運算符前後都有空格
$flag = 0;
// 關鍵詞 if 與括弧之間必須有一個空格,括弧內的 $ 與左括弧,0 與右括弧不需要空格
if ($flag == 0) {
echo 0;
}
// 左大括弧前加空格且不換行;左大括弧後換行
if ($flag == 1) {
echo 1;
// 右大括弧前換行,右大括弧後有 else,不用換行
} else {
echo 0;
// 在右大括弧後直接結束,則必須換行
}
}
1.5.5.1 if,elseif,else
1)【強制】一個if結構看起來應該像下麵這樣。註意[括弧],[空格],[花括弧]的位置;並且 else 和 elseif和前一個主體的右花括弧在同一行。
2)【強制】關鍵詞 elseif 應該替代 else if 使用以保持所有的控制關鍵詞像一個單詞。
正例:
$flag = 0;
// 關鍵詞 if 與括弧之間必須有一個空格,括弧內的 $ 與左括弧,0 與右括弧不需要空格
if ($flag == 0) {
echo 0;
}
// 左大括弧前加空格且不換行;左大括弧後換行
if ($flag == 1) {
echo 1;
// 右大括弧前換行,右大括弧後有 else,不用換行
} else {
echo 0;
// 在右大括弧後直接結束,則必須換行
}
1.5.5.2 switch, case
1)【強制】一個 switch 結構看起來應該像下麵這樣。註意[括弧],[空格]和[花括弧]。case 語句必須從 switch 處縮進,並且 break 關鍵字(或其他中止關鍵字)必須和 case 主體縮進在同級。如果一個非空的 case 主體往下落空則必須有一個類似// no break 的註釋。
正例:
//關鍵詞 switch 與括弧之間必須有一個空格,括弧內的 $ 與左括弧,2 與右括弧不需要空格
switch ($expr2) {//左大括弧前加空格且不換行;左大括弧後換行
//縮進4個空格,關鍵詞case與0之間必須有一個空格
case 0://冒號前沒空格,冒號後換行
//主體縮進4個空格
echo 'First case, with a break';
//case主體內容必須有break作為結尾
break;
case 1:
echo 'Second case, which falls through';
//沒有break必須得no break註釋
// no break case 1:
case 2:
echo 'Third case, return instead of break';
//用return代替break;
return;
default:
//預設case
echo 'Default case';
break;
}
1.5.5.3 while, do while
1)【強制】一個 while 語句看起來應該像下麵這樣。註意括弧,[空格]和[花括弧]的位置。
正例:
//關鍵詞while與左括弧之間必須有一個空格,$與左括弧,1與有括弧之間不需要空格
while ($expr1) {//左大括弧前加空格且不換行,左大括弧後換行
//縮進四個空格
echo 1;
}
2)【強制】同樣的,一個 do while 語句看起來應該像下麵這樣。註意[括弧],[空格]和[花括弧]的位置。
正例:
//關鍵詞do與左大括弧之間必須有一個空格
do {//左大括弧直接換行
//縮進4個空格
echo 1;
} while ($expr1);//關鍵詞while與右大括弧之間有一個空格且不換行,與左括弧之間必須有一個空格,$與左括弧,1與有括弧之間不需要空格
1.5.5.4 for
1)【強制】一個for 語句看起來應該像下麵這樣。註意[括弧],[空格]和[花括弧]的位置。
正例:
//關鍵詞for與左括弧之間必須有一個空格,$與左括弧,+與有括弧之間不需要空格,分號後有一個空格
for ($index = 0; $index < 10; $index++) {//左大括弧前加空格且不換行;左大括弧後換行,運算符兩側都有空格
//縮進4個空格
echo 1;
}
1.5.5.5 foreach
1)【強制】一個foreach 語句看起來應該像下麵這樣。註意[括弧],[空格]和[花括弧]的位置。
正例:
$iterable = [1,2,3,4];
//關鍵詞foreach與左括弧之間必須有一個空格,$與左括弧,e與有括弧之間不需要空格
foreach ($iterable as $key => $value) {//左大括弧前加空格且不換行;左大括弧後換行,as和=>兩側都有空格
echo 1;
}
1.5.5.6 try, catch
1)【強制】一個try catch 語句看起來應該像下麵這樣。註意[括弧],[空格]和[花括弧]的位置。
正例:
//關鍵詞try與左大括弧之間必須有一個空格
try {//左大括弧後面直接換行
//縮進4個空格
echo '1';
//關鍵詞catch兩側都有一個空格,F與左括弧,e與右括弧之間沒有空格
} catch (FirstExceptionType $e) {//右括弧與左大括弧之間有空格,右大括弧後換行
echo 2;
} catch (OtherExceptionType $e) {
echo 3;
}
1.5.6 運算符
1)【強制】每個運算符與兩邊參與運算的值或表達式中間要有一個空格;
正例:a=1;a = 1; a=1;c > d;d; d;a == b;b; b;a = b;b; b;c = a+a + a+b;
反例:b=1;b=1; b=1;c>d;d; d;a==b;b; b;a=b;b; b;c=a+a+a+b;
1.5.7 引號
1)【推薦】在絕大多數可以使用單引號的場合,禁止使用雙引號(性能考慮)。可以或必須使用單引號的情況包括但不限於下述:
u 字元串為固定值,不包含“\t”等特殊轉義字元;
u 數組的固定下標,例如$array['key'];
u 表達式中不需要帶入變數,例如string=′test′;,而非string = 'test';,而非string=′test′;,而非string = "test$var";
正例:array\['key'\]; a = 'test'; a="testtrn";a = "test\\t\\r\\n"; a="testtrn";b = "test$b";
反例:array\["key"\]; a = "test"; a=′testtrn′;a = 'test\\t\\r\\n '; a=′testtrn′;a = ' test$b ';
1.5.8 關鍵詞
1)【強制】PHP keywords 必須使用小寫。
正例:for public foreach static use extends
反例:FOR PUBLIC FOREACH STATIC USE EXTENDS
2)【強制】PHP 常量 true, false 和 null 必須使用小寫。
正例:true false null
反例:TRUE FALSE NULL
1.5.9 函數
和3.5.12類似,只是不需要申明可見性
1.5.10 類
1)【強制】類必須單獨一個源文件,並且類名和文件名相同。
2)【強制】類的左花括弧必須放到下一行,右花括弧必須放在類主體的下一行。
3)【強制】類文件“?>”結束標記去掉
4)【強制】一個類的 extends 和 implements 關鍵詞必須和類名在同一行。
5)【強制】implements 一個列表可以被拆分為多個有一次縮進的後續行。如果這麼做,列表的第一項必須要放在下一行,並且每行必須只有一個介面。
正例:(涉及1-7點)
// extends 和 implements 關鍵詞必須和類名在同一行
class ClassName extends ParentClass implements
//介面列表拆分成多個換行,每行只能有一個介面
ArrayAccess,
Countable,
Serializable
{//花括弧單獨占一行,左花括弧後換行
//縮進4個空格
public function test()
{
}
}
1.5.11 屬性
1)【強制】所有的屬性必須聲明可見性。
2)【強制】var 關鍵詞不可用來聲明屬性。
3)【強制】一個語句不可聲明多個屬性。
4)【推薦】屬性名稱可以使用單個下劃線作為首碼來表明保護或私有的可見性。
正例:(涉及1-4點)
class ClassName
{
//public設置為公有屬性,必須的設置屬性的可見性
public $foo = null;
//可以用_首碼來標識內部變數
private $_bar = 1;
}
反例:(涉及1-4點)
class ClassName
{
//沒有申明屬性可見性
$foo = null;
//不能使用var來申明屬性
var $foo = 1;
//一條語句不能申明兩個屬性
public $a,$b;
}
1.5.12 方法
1)【強制】所有的方法必須聲明可見性。
2)【強制】不超過200行代碼,儘可能的拆分、復用。
3)【推薦】方法名不應只使用單個下劃線來表明是保護或私有的可見性。
4)【強制】方法名在聲明之後不可跟隨一個空格。左花括弧必須放在下麵自成一行,並且右花括弧必須放在方法主體的下麵自成一行。左括弧後面不可有空格,右括弧前面不可有空格。
5)【強制】在參數列表中,逗號之前不可有空格,逗號之後必須要有一個空格。
6)【強制】方法中有預設值的參數必須放在參數列表的最後面。
7)【強制】參數列表可以被分為多個有一次縮進的多個後續行。如果這麼做,列表的第一項必須放在下一行,並且每行必須只放一個參數。
8)【強制】當參數列表被分為多行,右括弧和左花括弧必須夾帶一個空格放在一起自成一行。
9)【強制】如果存在,abstract 和 final 聲明必須放在可見性聲明前面。
10)【強制】如果存在,static 聲明必須跟著可見性聲明。
正例:(涉及1-10點)
class Test
{
//聲明必須放在可見性聲明前面 static必須放在可見性申明之後,$與左括弧,]與右括弧之間都沒有空格
abstract public static function hello($arg1, &$arg2, $arg3 = [])//參數後緊跟逗號,逗號後有一個空格,預設參數放在最後
{//左花括弧必須單獨成一行
//縮進8個空格
echo 1;
}
//多個參數換行
abstract public static function test(
//參數列表換行 列表的第一項必須放在下一行,並且每行必須只放一個參數
$arg1,
&$arg2,
array $arg3 = []
) {
//當參數列表被分為多行,右括弧和左花括弧必須夾帶一個空格放在一起自成一行
echo 2;
}
}