萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 程式碼風格規範完整指南 (參考 SINA、phpDocumentor 標準)

良好的程式碼風格能提升可讀性、維護性與團隊協作效率。本文整理自 SINA 開發規範、PHP4 開發規範與 phpDocumentor 標準,涵蓋命名、版面、註解三大面向。

第 1 章:命名規範

1.1 變數

類型規則範例
全域變數$g_ 開頭$g_data_list
一般變數小寫 + 下底線分隔單字,名詞或 形容詞+名詞$value, $new_value
暫存變數迴圈計數器 $i、$j 等勿挪作他用$i, $j, $k

1.2 函式

  • 小寫 + 下底線分隔
  • 動詞 + 名詞:get_user_img(), save_order_data()
  • 相關函式群組放同一檔案:function_user.func.php

1.3 類別

  • PascalCase:PageManager, UserController
  • 方法前、屬性後;public 方法前、private 方法後
  • 一類一檔:ClassName.class.php;緊密相關類別可共檔

1.4 方法

  • camelCase:getCurrentPage(), setUserName()
  • 避免生僻縮寫:where2go() ❌
  • 常用縮寫只大寫首字母:getHtml(), parseXml()

第 2 章:版面規則

2.1 語義分隔

  • 函式/方法之間空一行
  • 緊密相關語句可不換行,其餘需換行

2.2 空格規則

2.3 字串串接

// 正確:點號前後加空格
$name = 'file_' . $var1;

// 正確:雙引號用大括號包變數
$name = "file_{$var1}";

// 錯誤
$name = "file_$var1";      // 易誤讀
$name = 'file_' .$var1;    // 空格不一致

2.4 括號規則

  • 函式名後括號不加空格:strlen($name)
  • 關鍵字後括號加空格:for ($i = 0; ...)

2.5 大括號風格

// 正確:K&R 風格,大括號另起一行
if ($condition) 
{
    $action();
}

// 錯誤:大括號同行
if ($condition) {
    $action();
}

2.6 陣列鍵名

// 正確:鍵名加單引號
$arr = array('name' => '', 'gender' => '');
$val = $user_info['name'];

// 錯誤:裸露常數
$arr = array(name => '', gender => '');
$val = $user_info[name];

2.7 SQL 寫法

// 正確:關鍵字大寫、識別符用反引號、值用單引號並轉義
$sql = "SELECT `user`.`name` FROM `user` WHERE `id` = '$id' LIMIT 1";

// 錯誤
$sql = "select name.user from name where id = $id";

第 3 章:註解規範 (phpDocumentor 格式)

3.1 原則

  • 不寫廢話註解;程式碼自述時才補充邏輯說明
  • 註解視為程式一部分,同步維護
  • 全採 phpDocumentor 格式,可自動產生 API 文件

3.2 關鍵區塊範本

檔案標頭

/**
 * 所有內嵌標籤的抽象表示都在這個檔案
 * @package phpDocumentor
 * @subpackage InlineTags
 * @since separate file since version 1.2
 * @version $Id$
 */

類別註解

/**
 * 用於代表 {@link} 這類內嵌標籤
 * @see parserStringWithInlineTags
 * @package phpDocumentor
 * @subpackage InlineTags
 * @author Greg Beaver <cellog@users.sourceforge.net>
 * @since 1.0rc1
 * @version $Revision: 1.21.2.6 $
 * @tutorial inlinetags.pkg
 */

屬性註解

/**
 * 元素類型
 * @var string
 */
var $type = 'inlinetag';

方法註解

/**
 * 取得簡短描述
 * @return string 永遠回傳空字串
 * @see parserStringWithInlineTags::getString()
 * @see parserStringWithInlineTags::trimmedStrlen()
 */
function getString() {
    return '';
}

現代補充建議

  • 採用 PSR-12 作為基準風格 (現代 PHP 社群標準)
  • 使用 PHP_CodeSniffer + PHP-CS-Fixer 自動檢查修正
  • 類型宣告:PHP 7.4+ 使用型別提示 function getUser(int $id): User
  • 嚴格模式:declare(strict_types=1);
copyright © 萬盛學電腦網 all rights reserved
情境正確錯誤
邏輯運算子前後$a == $b$a==$b, $a ==$b
遞增遞減運算子$a++; $a--;$a ++; $a --;
多參數分隔func($a, $b, $c)func($a,$b,$c)
關鍵字後for ($i = 0; ...)for($i = 0; ...)