WordPress 的 PHP風格指南摘要
最近想要更新自己的 WordPress 主題,所以又嘗試去重新熟悉有關 PHP 的開發與 WordPress 的程式設計風格指南。
這篇是 WordPress 的 PHP 風格指南的摘要,這些摘要都是來自我對指南理解的簡短筆記,並不一定等於原話。算是協助我之後要重新進入這個開發情境的回憶索引吧!想要參考程式碼範例與暸解這樣制定的原因,請直接參考原文指南。
此篇摘要為初版,未來可能會為了方便記憶去編寫更好閱讀的版本。
PHP風格指南摘要
- Single and Double Quotes
- 預設使用單引號 (
'
),有變數才用雙引號 ("
)。 - 避免在字串中使用跳脫引號(
\"
)。 - 放在 HTML 屬性的變數必須使用
esc_attr()
去跳脫。
- 預設使用單引號 (
- Indentation
- 行首縮排應使用 tab 而不是 space。(註:我本人是 space 派的 QQ)。
- 在行首縮排使用 tab 排版,在行中使用 space 對齊。
- 關聯式陣列,每個項目應該都要獨立一行,且必須有逗號放在行尾。
- switch 區塊中,case 前必有一縮排,case 區塊內的敘述則再一層縮排。
- Brace Style
- 前大括號應放在敘述的行尾,而不是獨立一行。
- 後大括號後面若仍有敘述,則為同一行 (eg.
} else
)。 - 就算區塊裡只有一行敘述,仍需使用大括號。
- Use
elseif
, notelse if
- Declaring Arrays
- 使用較完整的陣列宣告語法,確保更好的可讀性,對視覺障礙者也較友善。
[ 1, 2, 3 ]
->array( 1, 2, 3 )
- Closures (Anonymous Functions)
- 不要透過匿名函式傳遞 filter 或 action 的 callback,這樣會導致無法移除 filter 或 action。
- Multiline Function Calls
- 如果函式呼叫有需要多行呈現的情況,每項參數與註解,都應該獨立一行,且不得超過一行。
- Regular Expressions
- 使用
preg_replace_callback
,而不用/e
,後者會帶來安全性問題。 - 使用單引號包覆正則表達式的敘述。
- 使用
- Opening and Closing PHP Tags
- 在 PHP 程式碼多行的情況下,PHP 的開合標籤應獨立一行。
- No Shorthand PHP Tags
- 務必使用完整的 PHP 開合標籤
<?php
,而不使用短語法<?
。
- 務必使用完整的 PHP 開合標籤
- Remove Trailing Spaces
- 務必移除行尾多餘的空白。
- 盡量在檔案終行使用 PHP 收合標籤。
- Space Usage
- 務必在逗號之後加上空白 (space)。
- 務必在邏輯、比較、字串、賦值運算元兩側加上空白。
- 在小括號內側若有敘述或引數,務必在內側兩邊加上空白。
- 在
if
,elseif
,foreach
,for
,switch
這類語法的小括號外面兩側加上空白。 - 函式名稱與前小括號之間不用留空白。
- 強制轉型的型別務必使用小寫,並使用短寫。
- 在參考陣列用的引數中,只有在索引是使用變數時,才需要在內側兩邊都加空白。
- 在
switch
區塊中, case 的索引與冒號之間不該留空白。 - 承上,在函式定義返回值的型別時用的冒號,前方也不該留空白。
- Formatting SQL statements
- SQL 的關鍵字永遠以大寫書寫。
- 使用
$wpdb->prepare()
處理含有變數的 SQL 敘述。
- Database Queries
- 避免直接操作資料庫,而是使用既有的函式取得需要的值。
- Naming Conventions
- 變數、函式與 action/filter 永遠使用全小寫的 Snake Case
- 類別名稱使用每個詞首字大寫的 Snake Case,若是縮寫則永遠使用大寫表示。
- 常數使用全大寫的 Snake Case。
- 檔案名稱使用 Kebab Case。
- Class 檔案名稱則需要加上
class-
作為前綴。 - 呈上,如果該類別是 BackPress 的一部分,在改用
class.
作為前綴。 - 若是為在
wp-includes/
中,包含 template tags 的檔案,則應該以-template
作為後綴。
- Self-Explanatory Flag Values for Function Arguments
- 在函式的引數中,盡量避免使用布林型別,而是使用字串型別來增加語意。
- 如果函式需要許多參數,則建議可以改用
$args
陣列替代。
- Interpolation for Naming Dynamic Hooks
- 若使用動態命名的 Hooks 時,務必用大括號將不同的變數區隔出來,以增加可讀性 (eg.
{$new_status}_{$post->post_type}
)。
- 若使用動態命名的 Hooks 時,務必用大括號將不同的變數區隔出來,以增加可讀性 (eg.
- Ternary Operator
- 在使用三元運算子時,永遠用來測試是否相等,而不是測試是否相異。
- 僅在賦值的情境使用三元運算子,而不要在三元運算子中執行敘述、函式。
- Yoda Conditions
- 在條件式使用使用相等或相異的運算子時,永遠將變數放在右側。(儘管閱讀會不習慣,但在除錯時很有用)
- Clever Code
- 編寫敘述時,可讀性的重要程度永遠高過於使用奇巧、或過於簡潔的方式
- 務必使用嚴謹的比較運算子
===
,除了必要時才使用==
,以避免不合預期的行為。 - 永遠不要在條件式中賦值。
- 在 switch 敘述中,可以使用無敘述的 case 讓他往下執行。若是有敘述的 case 仍希望往下執行,則需要顯性的註解去表示是刻意不寫
break
。 - 永遠不要使用
goto
。 - 永遠不要使用
eval()
與create_function()
。
- Error Control Operator @
- 永遠不要使用
@
去忽略錯誤訊息。
- 永遠不要使用
- Don’t extract()
- 永遠不要使用
extract()
,他會導致難以除錯。
- 永遠不要使用