PHP書寫規範 匈牙利命名法+駝峯法命名

PHP書寫規範 PHP Coding Standard

變量命名規範這裏感受 打算採用 匈牙利命名法+駝峯法命名，由於 PHP是弱類型語言，不少時間由於忽略了變量類型而致使犯一些低級錯誤。因此在前面加上類型名有助於更好的理解代碼。

 

下載是轉載

PHP書寫規範
做者：sink <sink.cup@gmail.com>
最後修改：2011-7-13

參考資料：
PHP Manual
http://www.php.net/manual/zh/language.oop5.basic.php
PEAR Coding Standards
http://pear.php.net/manual/en/standards.php
C++ Coding Standard
http://www.possibility.com/Cpp/CppCodingStandard.html
Google C++ Style Guide
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
Code Conventions for the Java
http://www.oracle.com/technetwork/java/codeconvtoc-136057.html

制定規範時要注意：
一、通常不要出現2個都行的狀況。
好比tab和4個空格都行，結果致使代碼混亂。

通用原則：
一、語義化
看到名字，就知道意思。

二、通用前綴
is表示是否、get表示讀、set表示寫。is後面優先跟形容詞，而不是名詞，好比是否多語言文字，應使用is_multilingual，而不是is_multilanguage。

三、單數與複數
參考js的函數命名規則：getElementById、getElementsByTagName、getElementsByName。
例如：
取個人多個好友的名字，應使用getFriendsName，而不是getFriendNames或者getFriendName
取一個用戶，是getUser
取多個用戶，是getUsers

四、冗餘後綴
儘可能不使用data、list、info後綴，除非特殊狀況。
好比，js的命名就很注意，使用getElementsByTagName而不是getElementsInfoByTagName。
應該使用getFriends或者getFriendsUserId，而不是getFriendsList；應該使用getUser，而不使用getUserInfo或者getUserData。
不過有時候很難避免，好比有2個函數，分別是取用戶基本信息，和取用戶詳細信息。
取用戶基本信息：暱稱、頭像URI，函數名getUserBasic仍是getUserBasicInfo？函數名以形容詞結尾感受不合適。待討論。討論結果：getUserBasicInfo合適。
取用戶詳細信息：暱稱、頭像URI、簽名、生日，函數名getUser沒問題。

五、含義模糊的類名、文件名、目錄名
每當使用common、util、functions、class、object、basic做爲文件名時要慎重，因爲這些詞太通用，發展下去裏面東西可 能愈來愈多，變成垃圾箱。要給這些起一個準確的名字，好比要作字符串處理的類，能夠叫StringLib.php，放在lib目錄裏。

六、lib、plugin與addon的區別
有些類、函數算作lib、plugin仍是addon。待討論。討論結果：目前加強函數算是Lib，之後再考慮plugin和addon。

七、經常使用詞彙
優先使用URI，而不是URL。由於更嚴謹，新的命名開始使用URI。好比js的encodeURI，PHP的$_SERVER['REQUEST_URI']。
deadline與TTL：deadline表示最後時刻，TTL表示存活時間。好比如今時間是1310449710，TTL是60秒，則deadline是1310449710 + 60 = 1310449770。

類名：
大寫字母開頭，駝峯命名。通常使用名詞，好比配置解析類ConfigParser，而不是ParseConfig。
與Java、C++一致。
例如：class UserModel

類的文件名：
與類名相同。這與php autoload有關，爲了autoload，類名總要很長。待討論。討論結果：遵照駝峯，也能實現自動類載入。
與Java一致。
例如：class UserModel的文件名爲UserModel.php

非類文件名：
全小寫，下劃線分隔，不得使用空格。好比get_user.php。

目錄名：
全小寫，下劃線分隔，不得使用空格。好比model、www。

函數名：
小寫字母開頭，駝峯命名，例如：function addBlog()。
與Java、C++一致。
函數表示功能，即動做，因此動詞優先，例如使用editBlog，而不用blogEdit。
PHP內置函數因爲歷史緣由，有多種風格，do_something,something_do,dosomething,比較新的函數用了doSomething，才與目前主流語言保持一致。
好比：paser_str、json_encode、substr、fetchAll。
歷史緣由可能沒法改變，但咱們能保證新的代碼是嚴謹的，不要讓本身成爲歷史緣由。

類中的函數：
兩個函數中間空一行。若是有時間的話，各個函數按英文字母排序，省得太混亂。
例如：
class BlogModel
{
    public function addBlog()
    {

    }
    
    public function updateBlog()
    {

    }
}

文件註釋：
註釋緊跟<?php下一行。註明做者。@version暫不須要寫，由於svn提供了版本管理。
格式按照PHPdoc的要求：http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.author.pkg.html
<?php
/**
 * blog的各類業務：添加、更新
 * @author sink
 *
 */
class BlogModel
{

}
?>

API註釋：
必定要寫輸入參數，和輸出格式。寫清楚正確時輸出什麼，錯誤時輸出什麼。
不然別人沒法使用。

函數註釋：
必定要寫輸出格式。寫清楚正確時輸出什麼，錯誤時輸出什麼。
若是輸入參數比較複雜，包含數組，看參數沒法一目瞭然，則要寫輸入參數的註釋。
文檔註釋與函數之間不能有空行。
若是函數內部步驟比較複雜，須要寫「行內註釋」。
例如：
/**
 * 更新blog
 * @param int $id blog_id
 * @param array $data array(
    "content" => "", //內容
    "tags" => "", //標籤
    "update_time" => "", //更新時間
 )
  * @return bool
 */
public function updateBlog($id,$data)
{
    step1 //第一步：asdf
    step2 //第二步：qwer
}

URI：
根據rfc1034國際標準的規定，域名中禁止出現下劃線「_」，域名不區分大小寫。
好比http://dl_dir.qq.com/是錯誤域名。
http://example.com與http://EXAMPLE.COM相同。
因此優先在URI中使用全小寫，GET的name小寫，可是GET的值除外。
好比
http://www.google.com/?hl=zh-CN
http://www.google.com/?hl=zh-cn
URI中非參數的專有名詞的縮寫是否使用小寫，有爭議無定論。
好比
http://fedoraproject.org/zh_CN/
http://zh.wikipedia.org/zh-cn/
http://code.google.com/intl/zh-CN/
http://www.microsoft.com/en-us/
語言文字代碼是專有名詞，ISO規定必須是減號，且建議地區使用大寫。
fedora的用法很奇怪，使用了本身製造的zh_CN，而不是zh-CN。並且不建議在URI中使用下劃線。
wiki用了小寫，google用了大寫，微軟用了小寫。

優先在URI中使用減號「-」，而不是下劃線，GET的name除外。
好比
http://example.com/1-2-2
http://example.com/?user_id=123
若是但願用戶手動輸入URI，則不要區分大小寫，且優先使用小寫，由於用戶輸入更方便。
實際狀況是：用戶通常是手動輸入域名，而不手動輸入URI，由於URI很長。在這種狀況下，URI小寫是否有意義，若是使用 http://example.com/?userId=123，變量名就可使用駝峯$userId = $_GET['userId']，就可以和Java、C++保持一致，這樣數據庫也要駝峯命名。待討論。討論結果：使用?user_id=123。

變量：
全小寫，下劃線分隔，例如：$user_id。
與Java、C++不一致。討論結果：使用$user_id。
類的成員變量、函數的形參、類實例化成一個對象，都遵照變量的命名規則。
緣由：URI、數據庫有小寫慣例，從$_GET、$_POST中得到參數入庫，因此用小寫。
PHP內置變量$_GET、$_POST使用下劃線開頭，全大寫。自定義的變量不管多麼重要，都不要使用下劃線開頭，以避免未來與內置變量衝突。
好比：不要使用$_PUT、$_DELETE。

常量：
全大寫，下劃線分隔。例如：const MEMCACHE_TTL = 600;

PHP短標籤：
使用<?php ?>，不使用短標籤<? ?>。由於與xml衝突，且不利於部署。

類大括號換行：
能夠採用大括號單獨佔一行，也能夠大括號與別的放在一行，有爭議無定論，待討論。討論結果：使用「同行」。
class UserModel {

}
支持換行者：
http://www.php.net/manual/zh/language.oop5.basic.php
http://pear.php.net/manual/en/standards.classdef.php

函數大括號換行：
有爭議無定論，待討論。討論結果：使用「同行」。
function getUser() {

}
支持換行者：
http://www.php.net/manual/zh/language.oop5.basic.php
http://pear.php.net/manual/en/standards.funcdef.php

if大括號換行：
有爭議無定論，待討論。討論結果：使用「同行」。
例如：
if(!empty($name))
{

}
或者
if(!empty($name)) { //肯定

}
支持換行者：
http://www.possibility.com/Cpp/CppCodingStandard.html#brace

支持同行者：
http://www.php.net/manual/zh/language.oop5.basic.php
http://pear.php.net/manual/en/standards.control.php

switch大括號換行：
討論結果：使用「同行」。
switch (...) {
    case 1:
        ...
        break;

    default:
}
支持換行者：
http://www.possibility.com/Cpp/CppCodingStandard.html#switch

數組小括號換行：
有爭議無定論。討論結果：使用「同行」。
$user = array(
    "id" => "123",
    "name" => "user1",
    "email" => "a@example.com",
)
支持同行者：
http://pear.php.net/manual/en/standards.arrays.php

數組內部換行：
2維及以上數組的數組內部換行。
如
$user = array(
    'id' => '123',
    'name' => 'user1',
    'email' => 'a@example.com',
);
1維數組內部不換行。討論結果：1維數組內部不換行。
如
$users_id = array('23','12','24');//肯定

數組最後的逗號：
數組每一行最後要有逗號，這樣方便之後添加。不過前端JSON最後不能有逗號，不然有的瀏覽器不支持，待討論。討論結果：都行，由於後端不用考慮IE前端。
好比
$user = array(
    'id' => '123',
    'name' => 'user1', //都行，優勢：大數組，常常添加一行，方便。若是沒有逗號，確實太難以添加了。
);
$user = array(
    'id' => '123',
    'name' => 'user1' //都行，優勢：嚴謹，逗號表示分隔，最後一個不須要分隔。
);

單引號與雙引號：
優先使用單引號，當須要轉義時使用雙引號，變量不放在雙引號中。這與JSON不一樣，JSON全是雙引號，待討論。討論結果：優先使用單引號。
好比：
echo 'name is:' . $name . '.' . "\n";
$user = array(
    'id' => '123',
);

條件判斷的大括號：
必須有大括號，即便只有一行。
正確：
if(!empty($name)){
    doSomething();
}
錯誤：
if(!empty($name))
    doSomething();

回車換行：
使用換行LF（\n，0a，Unix風格）。不使用CR+LF（Windows風格）。
參考：http://zh.wikipedia.org/zh-cn/%E6%8F%9B%E8%A1%8C
eclipse——》workspace——》New text file line delimiter——》Other：Unix

編碼：
使用UTF-8 no BOM。不得使用Windows記事本進行保存，由於記事本是UTF-8 BOM CR+LF。
eclipse——》workspace——》Text file encoding——》Other：UTF-8

縮進：
使用4個空格進行縮進，也能夠採用tab進行縮進。討論結果：4個空格。
支持4個空格者：//肯定
http://www.oracle.com/technetwork/java/codeconventions-136091.html#262

支持2個空格者：
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Spaces_vs._Tabs

支持三、4或8個空格者：
http://www.possibility.com/Cpp/CppCodingStandard.html#indent

要保證縮進正確，若是使用4個空格，必定不要出現5個空格或者11個空格。
eclipse——》General——》Editor——》Text Editors——》show whitespace characters
vim ~/.vimrc
set expandtab
set softtabstop=4
set shiftwidth=4
set autoindent

HTTP協議緩存：
文章使用Last Modified表示最後修改時間，不由止緩存。
header('Last Modified:Sat, 30 Oct 2010 13:21:21 GMT');
須要用戶登陸的頁面，禁止緩存。
header('Cache-Control:max-age=0');
header('Cache-Control:private');

HTTP協議編碼與mime：
HTTP輸出必定要聲明編碼與mime。charset與分號之間要有一個空格。小寫utf-8仍是大寫UTF-8，還沒有找到文檔，待調研。
好比
header('Content-Type:application/json; charset=UTF-8');
header('Content-Type:application/xml; charset=UTF-8');
header('Content-Type:application/xhtml+xml; charset=UTF-8');
header('Content-Type:text/plain; charset=UTF-8');
header('Content-Type:text/html; charset=UTF-8');

專有名詞大小寫：
在類、函數、文件名、目錄名等各類地方，不特殊對待專有名詞，不採用全大寫。討論結果：使用小寫。
緣由：專有名詞難以界定，好比HTML、CSS、CRUD。並且全大寫致使與駝峯衝突，好比頁面助手類，全大寫是HTMLHelper，不如HtmlHelper。
支持不特殊處理：
HTML是專有名詞，但mime中就使用Content-Type:text/html，而不是text/HTML。
例子：
採用UserDb.php，而不是UserDB.php。