一、 編碼規約
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;
}
}
轉載請註明出處,本文鏈接:https://www.uj5u.com/houduan/501052.html
標籤:PHP
