深藏若虛

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, not else 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，而不使用短語法 <?。
  • 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})。
  • Ternary Operator
    • 在使用三元運算子時，永遠用來測試是否相等，而不是測試是否相異。
    • 僅在賦值的情境使用三元運算子，而不要在三元運算子中執行敘述、函式。
  • Yoda Conditions
    • 在條件式使用使用相等或相異的運算子時，永遠將變數放在右側。（儘管閱讀會不習慣，但在除錯時很有用）
  • Clever Code
    • 編寫敘述時，可讀性的重要程度永遠高過於使用奇巧、或過於簡潔的方式
    • 務必使用嚴謹的比較運算子 ===，除了必要時才使用 ==，以避免不合預期的行為。
    • 永遠不要在條件式中賦值。
    • 在 switch 敘述中，可以使用無敘述的 case 讓他往下執行。若是有敘述的 case 仍希望往下執行，則需要顯性的註解去表示是刻意不寫 break。
    • 永遠不要使用 goto。
    • 永遠不要使用 eval() 與 create_function()。
  • Error Control Operator @
    • 永遠不要使用 @ 去忽略錯誤訊息。
  • Don’t extract()
    • 永遠不要使用 extract()，他會導致難以除錯。
Information Technology , ,