良好的程式碼風格能提升可讀性、維護性與團隊協作效率。本文整理自 SINA 開發規範、PHP4 開發規範與 phpDocumentor 標準,涵蓋命名、版面、註解三大面向。
| 情境 | 正確 | 錯誤 |
| 邏輯運算子前後 | $a == $b | $a==$b, $a ==$b |
| 遞增遞減運算子 | $a++; $a--; | $a ++; $a --; |
| 多參數分隔 | func($a, $b, $c) | func($a,$b,$c) |
| 關鍵字後 | for ($i = 0; ...) | for($i = 0; ...) |
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