瞭解編碼標準的重要性

開啟 10/09/2024

1 意見

編碼標準就像是程式設計的文法規則。就像正確的語法能讓書面語言清晰易懂一樣，編碼標準也能讓您的程式碼一致易讀。

給您:您會發現將來閱讀和更新程式碼會更容易。
給其他人:如果您分享您的程式碼或在團隊中工作，其他人會欣賞您的清晰度。
適用於 WordPress:由於它是開放原始碼，許多人都有貢獻。標準讓一切保持統一。

編碼標準在團隊合作中的實際應用

想像您是一個大型團隊中 WordPress 專案的一員。每個人對程式碼都有不同的貢獻 - 有些人專注於後端，有些人專注於造型，有些人則專注於可存取性。如果沒有一致的標準，專案很快就會變得混亂。編碼標準可以確保

順利合作:當每個人都遵循相同的規則時，開發人員就更容易閱讀和理解彼此的工作。
減少合併衝突:格式不一致經常會在合併變更時導致程式碼衝突。標準可減少這些衝突，讓團隊更有效率地工作。
更好的上線:新加入專案的開發人員可以依照標準化的編碼風格快速上手，減少花在理解現有程式碼的時間。

考慮一個情況：開發人員離開專案，而新的團隊成員需要接手他們的部分。如果之前的開發人員遵循正確的編碼標準，則最新的成員可以快速加入、維護程式碼並進行改進，而無需花太多時間瞭解程式碼。

WordPress PHP 編碼標準

PHP 是 WordPress 的核心語言。遵循 PHP 編碼標準可確保您的程式碼能順利與 WordPress 整合，並讓其他人容易理解。

1.PHP 標籤：請務必使用完整的 PHP 標籤 <?php ?>.避免使用短標籤，例如 <? ?> 因為它們可能無法在所有伺服器上運作。

<?php
// Your PHP code here
?>

2.檔案編碼：以 UTF-8 儲存 PHP 檔案，不含 Byte Order Mark (BOM)。

3.行尾：使用 Unix 風格的行尾 (\n).

4.縮排：使用制表符進行縮排（而非空格）。這可讓程式碼在不同的編輯器中保持一致。

命名慣例

1.函數與方法：使用小寫字母和下劃線。

function get_user_data( $user_id ) {
    // 函式代碼
}

2.變數：與函數相同-小寫及下劃線。

$user_name = 'John Doe'；

3.Classes：使用大寫字詞 (StudlyCaps)。

類別 UserProfile {
// 類別代碼
}

4.常量：所有大寫字母均帶下劃線。

define( 'MAX_UPLOAD_SIZE', 1048576 )；

空白和縮排

1.逗號後的空格：列出參數或陣列項目時，每個逗號後都要加上一個空格。

$colors = array( 'red', 'green', 'blue' )；

2.控制結構：在控制關鍵字和開頭的括號之間放置一個空格。

if ( $condition ) {
    // 代碼
}

3.運算符號：在指定、比較和邏輯運算符號周圍包含空格。

$total = $price + $ax；
if ( $total > 100 ) {
    // 代碼
}

控制結構

1.支架位置：使用 Allman 風格，開頭的括号位于新行上。

if ( $condition )
{
    // 代碼
}
else
{
    // 代碼
}

2.否則** 關鍵字**：使用 否則 而非 else if.

if ( $condition )
{
    // 代碼
}
elseif ( $other_condition )
{
    // 代碼
}

3.Yoda 條件：將常數或文字放在比較的左側。

if ( true === $is_active )
{
    // 代碼
}

這有助於防止意外指派 (= 而非 ==).

最佳實務

1.避免使用速記 PHP 標籤：請務必使用完整的標籤，以獲得更好的相容性。

2.函數參數：使用清楚且具描述性的變數名稱。

函數 calculate_total( $subtotal, $ax_rate ) {
    // 代碼
}

3.Sanitize Inputs：務必對使用者輸入進行消毒和驗證。

$user_id = intval( $_GET['user_id'] )；

4.Escape 輸出：輸出資料前，請轉義資料以防止安全問題。

echo esc_html( $user_name )；

5.註解：使用註解來解釋複雜的邏輯或重要的注意事項。

// 計算含稅總價

內嵌文件標準

適當的文件可以讓您的程式碼更容易理解和維護。

1.函數註解：在每個函式之前，包含一個註解區塊。

/**
 * 計算含稅總價。
 *
 * @param float $subtotal 小計金額。
 * @param float $tax_rate 以小數表示的稅率。
 * @return float 總價。
 */
function calculate_total( $subtotal, $tax_rate ) { // 函式代碼
    // 函式代碼
}

2.參數和回傳值類型：指定每個參數和回傳值的類型。

3.內嵌註解：少用它們來解釋程式碼的複雜部分。

$discount = 0.0; // 初始化折扣變數

WordPress 中的 HTML 編碼標準

HTML 是網頁內容的骨幹。撰寫乾淨且符合語意的 HTML 對於可存取性和 SEO 來說至關重要。

一般指引

1.類型：永遠從 HTML5 doctype 開始。

<!DOCTYPE html>

2.語言屬性：在 <html> 標籤。

<html lang="en">

3.字元編碼：使用 UTF-8 編碼。

<meta charset="UTF-8">

架構您的 HTML

1.語意元素：使用 HTML5 語意元素，例如 <header>, <導航,

, <文章,

 標題
    

 導覽
    
</nav
<main
    <!

 <!
 <!

2.縮排：使用兩個空格（如果您喜歡，也可以使用制表符）來縮排巢狀元素。

<ul
    項目 1
    項目 2
</ul

3.屬性：屬性名稱使用小寫，屬性值使用雙引號包裝。

<img src="image.jpg" alt="令人讚嘆的圖片">

最佳實務

1.無障礙：總是包括 選項 屬性，並在適當的地方使用 ARIA 角色。

<img src="logo.png" alt="公司標誌">

2.自關閉標籤：對於 HTML5，您不需要自閉 void 元素，例如 <br>, <img>, <input>.

<br>
<img src="image.jpg" alt="說明">

3.註解：必要時使用 HTML 註解來解釋程式碼的部分。


</nav

WordPress 中的 CSS 編碼標準

CSS 控制著網站的呈現。撰寫乾淨且有效率的 CSS 可以讓您的網站看起來更美觀、載入速度更快。

一般指引

1.語法：遵循標準 CSS 語法 - 選擇器、大括號、屬性值對。

.class-selector {
    property: value；
}

2.縮排：規則內的縮排使用兩個空格（或制表符）。

3.註解：使用註解來分隔章節和解釋複雜的規則。

/* 標題樣式 */
標頭 {
    /* 屬性 */
}

撰寫乾淨的 CSS

1.選擇器名稱：使用小寫字母和連字線。

.main-navigation {
    /* 樣式 */
}

2.避免使用 ID 來做造型：使用類別而非 ID 來降低特定性。

/* 正確 */
.button {
    /* 風格 */
}

/* 避免 */
#submit-button {
    /* 風格 */
}

3.速記屬性：盡可能使用速記屬性。

/* 正確 */
margin: 10px 5px 15px 0；

/* 擴展 */
margin-top: 10px；
margin-right: 5px；
margin-bottom：15px；
margin-left: 0；

4.零值：省略零值的單位。

padding：0;

最佳實務

1.組織樣式：將相關的樣式組合在一起，例如版面設計、排版、顏色。

2.區段註解：使用註解將樣式表分為不同區段。

/* 排版 / / 顏色 / / 佈局 */

3.Avoid !important: 使用特定性而非 !important 來覆寫樣式。

4.媒體查詢：將媒體查詢放在相關樣式附近或獨立的部分。

@media (max-width: 768px) {
    .main-navigation {
        display: none；
    }
}

推薦工具與外掛程式

為了幫助您確保遵循 WordPress 編碼標準，請考慮使用下列工具：

PHP CodeSniffer:這個工具可以幫助偵測違反 WordPress PHP 編碼標準的情況。您可以使用 WordPress 編碼標準規則集來自動檢查您的程式碼。
編輯器設定:許多 IDE 和程式碼編輯器都支援 .editorconfig 檔案，這有助於在不同編輯器和開發人員之間維持一致的編碼樣式。
ESLint 和 Stylelint:使用這些工具來檢查 JavaScript 和 CSS，以找出常見的錯誤並執行一致性。
更漂亮:程式碼格式化工具，可自動強制 HTML、CSS 和 JavaScript 採用一致的樣式，讓團隊更容易維持統一的程式碼樣式。
VSCode 延伸:
- PHP Intelephense:提供智慧型自動完成和功能提示，並偵測潛在問題。
- WordPress 摘要:收集了常用的 WordPress 功能和片段，以加快開發速度。

應避免的常見錯誤

1.命名不一致： 混合使用 camelCase 和 snake_case 可能會導致混淆，因此請在整個專案中遵守規定的命名慣例。

2.不轉義輸出：在輸出使用者產生的內容前，請務必先將其轉義，以防止 XSS 等安全漏洞。

// 正確
echo esc_html( $user_input )；

// 不正確
echo $user_input；

3.不當使用全球資訊:除非必要，否則避免使用全局變數。相反地，明確地將變數傳給函數，以保持您的程式碼模組化，並且更容易測試。

4.使用內嵌樣式:應避免使用內嵌式樣式，因為它們會增加 CSS 的維護和覆寫難度。請務必使用外部樣式表。

把所有東西放在一起

讓我們看一個依照 WordPress 編碼標準結合 PHP、HTML 和 CSS 的範例。

範例：簡單的 PHP 模板

PHP 檔案 (template-example.php):

<?php
/**
 * Template Name: Example Template
 *
 * A template to demonstrate coding standards.
 *
 * @package WordPress
 * @subpackage Your_Theme
 */

get_header(); ?>

<main id="main-content" class="site-main">
    <?php
    if ( have_posts() ) :
        while ( have_posts() ) :
            the_post(); ?>

            <article id="post-<?php the_ID(); ?>" no numeric noise key 1006>
                <header class="entry-header">
                    <?php the_title( '<h1>', '</h1>' ); ?>
                </header>

                <div class="entry-content">
                    <?php the_content(); ?>
                </div>
            </article>

        <?php endwhile;
    else : ?>

        <p><?php esc_html_e( 'Sorry, no posts matched your criteria.', 'your-text-domain' ); ?></p>

    <?php endif; ?>
</main>

<?php get_footer(); ?>

CSS 檔案 (style.css):

/* 主內容樣式 */
.site-main {
    margin: 0 auto；
    max-width: 800px；
    padding：20px；
}

.entry-header h1 {
    font-size: 2em；
    margin-bottom：0.5em；
}

.entry-content {
    line-height: 1.6；
}

其他資源