PHP書寫規(guī)范
PHP書寫規(guī)范
作者：sink
***修改：2011-7-7
參考資料：
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
通用原則：
1、語義化
看到名字，就知道意思。
2、通用前綴
is表示是否、get表示讀、set表示寫。is后面優(yōu)先跟形容詞，而不是名詞，比如是否多語言文字，應使用is_multilingual，而不是is_multilanguage。
3、單數(shù)與復數(shù)
參考js的函數(shù)命名規(guī)則：getElementById、getElementsByTagName、getElementsByName。
例如：
取我的多個好友的名字，應使用getFriendsName，而不是getFriendNames或者getFriendName
取一個用戶，是getUser
取多個用戶，是getUsers
4、冗余后綴
盡量不使用data、list、info后綴。
比如，js的命名就很注意，使用getElementsByTagName而不是getElementsInfoByTagName。
應該使用getFriends或者getFriendsUserId，而不是getFriendsList;應該使用getUser，而不使用getUserInfo或者getUserData。
不過有時候很難避免，比如有2個函數(shù)，分別是取用戶基本信息，和取用戶詳細信息。
取用戶基本信息：昵稱、頭像URI，函數(shù)名getUserBasic還是getUserBasicInfo?函數(shù)名以形容詞結尾感覺不合適，待討論。
取用戶詳細信息：昵稱、頭像URI、簽名、生日，函數(shù)名getUser沒問題。
5、含義模糊的類名、文件名、目錄名
每當使用common、util、functions、class、object、basic作為文件名時要慎重，由于這些詞太通用，發(fā)展下去里面東西可 能越來越多，變成垃圾箱。要給這些起一個準確的名字，比如要做字符串處理的類，可以叫StringLib.php，放在lib目錄里。
6、lib、plugin與addon的區(qū)別
有些類、函數(shù)算做lib、plugin還是addon。待討論。
類名：
大寫字母開頭，駝峰命名。一般使用名詞，比如配置解析類ConfigParser，而不是ParseConfig。
與Java、C++一致。
例如：class UserModel
類的文件名：
與類名相同。這與php autoload有關，為了autoload，類名總要很長，待討論。
與Java一致。
例如：class UserModel的文件名為UserModel.php
非類文件名：
全小寫，下劃線分隔，不得使用空格。比如get_user.php。
目錄名：
全小寫，下劃線分隔，不得使用空格。比如model、www。
函數(shù)名：
小寫字母開頭，駝峰命名，例如：function addBlog()。
與Java、C++一致。
函數(shù)表示功能，即動作，所以動詞優(yōu)先，例如使用editBlog，而不用blogEdit。
PHP內(nèi)置函數(shù)由于歷史原因，有多種風格，do_something,something_do,dosomething,比較新的函數(shù)用了doSomething，才與目前主流語言保持一致。
比如：paser_str、json_encode、substr、fetchAll。
歷史原因可能無法改變，但我們能保證新的代碼是嚴謹?shù)模灰屪约撼蔀闅v史原因。
類中的函數(shù)：
兩個函數(shù)中間空一行。如果有時間的話，各個函數(shù)按英文字母排序，免得太混亂。
例如：
- 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的各種業(yè)務：添加、更新
- * @author sink
- *
- */
- class BlogModel
- {
- }
- ?>
API注釋：
一定要寫輸入?yún)?shù)，和輸出格式。寫清楚正確時輸出什么，錯誤時輸出什么。
否則別人無法使用。
#p#
函數(shù)注釋：
一定要寫輸出格式。寫清楚正確時輸出什么，錯誤時輸出什么。
如果輸入?yún)?shù)比較復雜，包含數(shù)組，看參數(shù)無法一目了然，則要寫輸入?yún)?shù)的注釋。
文檔注釋與函數(shù)之間不能有空行。
如果函數(shù)內(nèi)部步驟比較復雜，需要寫“行內(nèi)注釋”。
例如：
- /**
- * 更新blog
- * @param int $id blog_id
- * @param array $data array(
- "content" => "", //內(nèi)容
- "tags" => "", //標簽
- "update_time" => "", //更新時間
- )
- * @return bool
- */
- public function updateBlog($id,$data)
- {
- step1 //***步：asdf
- step2 //第二步：qwer
- }
URI：
根據(jù)rfc1034國際標準的規(guī)定，域名中禁止出現(xiàn)下劃線“_”，域名不區(qū)分大小寫。
比如http://dl_dir.qq.com/是錯誤域名。
http://example.com與http://EXAMPLE.COM相同。
所以優(yōu)先在URI中使用全小寫，GET的name小寫，但是GET的值除外。
比如
http://www.google.com/?hl=zh-CN
http://www.google.com/?hl=zh-cn
URI中非參數(shù)的專有名詞的縮寫是否使用小寫，有爭議無定論。
比如
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規(guī)定必須是減號，且建議地區(qū)使用大寫。
fedora的用法很奇怪，使用了自己制造的zh_CN，而不是zh-CN。而且不建議在URI中使用下劃線。
wiki用了小寫，google用了大寫，微軟用了小寫。
優(yōu)先在URI中使用減號“-”，而不是下劃線，GET的name除外。
比如
http://example.com/1-2-2
http://example.com/?user_id=123
如果希望用戶手動輸入URI，則不要區(qū)分大小寫，且優(yōu)先使用小寫，因為用戶輸入更方便。
實際情況是：用戶一般是手動輸入域名，而不手動輸入URI，因為URI很長。在這種情況下，URI小寫是否有意義，如果使用 http://example.com/?userId=123，變量名就可以使用駝峰$userId = $_GET['userId']，就能夠和Java、C++保持一致，這樣數(shù)據(jù)庫也要駝峰命名。待討論。
變量：
全小寫，下劃線分隔，例如：$user_id。
與Java、C++不一致。待討論。
類的成員變量、函數(shù)的形參、類實例化成一個對象，都遵守變量的命名規(guī)則。
原因：URI、數(shù)據(jù)庫有小寫慣例，從$_GET、$_POST中獲得參數(shù)入庫，所以用小寫。
PHP內(nèi)置變量$_GET、$_POST使用下劃線開頭，全大寫。自定義的變量無論多么重要，都不要使用下劃線開頭，以免將來與內(nèi)置變量沖突。
比如：不要使用$_PUT、$_DELETE。
常量：
全大寫，下劃線分隔。例如：const MEMCACHE_TTL = 600;
PHP短標簽：
使用，不使用短標簽。因為與xml沖突，且不利于部署。
類大括號換行：
可以采用大括號單獨占一行，也可以大括號與別的放在一行，有爭議無定論，待討論。
- class UserModel
- {
- }
支持換行者：
http://www.php.net/manual/zh/language.oop5.basic.php
http://pear.php.net/manual/en/standards.classdef.php
#p#
函數(shù)大括號換行：
有爭議無定論，待討論。
- function getUser()
- {
- }
支持換行者：
http://www.php.net/manual/zh/language.oop5.basic.php
http://pear.php.net/manual/en/standards.funcdef.php
if大括號換行：
有爭議無定論，待討論。
例如：
- if(!emptyempty($name))
- {
- }
或者
- if(!emptyempty($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
數(shù)組小括號換行：
有爭議無定論，待討論。
- $user = array(
- "id" => "123",
- "name" => "user1",
- "email" => "a@example.com",
- )
支持同行者：
http://pear.php.net/manual/en/standards.arrays.php
數(shù)組內(nèi)部換行：
2維及以上數(shù)組的數(shù)組內(nèi)部換行。
如
- $user = array(
- 'id' => '123',
- 'name' => 'user1',
- 'email' => 'a@example.com',
- );
1維數(shù)組內(nèi)部不換行?待討論。
如
- $users_id = array('23','12','24');
數(shù)組***的逗號：
數(shù)組每一行***要有逗號，這樣方便以后添加。不過前端JSON***不能有逗號，否則有的瀏覽器不支持，待討論。
比如
- $user = array(
- 'id' => '123',
- 'name' => 'user1', //正確
- );
- $user = array(
- 'id' => '123',
- 'name' => 'user1' //錯誤
- );
#p#
單引號與雙引號：
優(yōu)先使用單引號，當需要轉義時使用雙引號。這與JSON不同，JSON全是雙引號，待討論。
比如：
- echo 'name is:' . $name . '.' . "\n";
- $user = array(
- 'id' => '123',
- );
條件判斷的大括號：
必須有大括號，即使只有一行。
正確：
- if(!emptyempty($name))
- {
- doSomething();
- }
錯誤：
- if(!emptyempty($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個空格者：
http://www.oracle.com/technetwork/java/codeconventions-136091.html#262
支持2個空格者：
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Spaces_vs._Tabs
支持3、4或8個空格者：
http://www.possibility.com/Cpp/CppCodingStandard.html#indent
要保證縮進正確，如果使用4個空格，一定不要出現(xiàn)5個空格或者11個空格。
eclipse——》General——》Editor——》Text Editors——》show whitespace characters
vim ~/.vimrc
set expandtab
set softtabstop=4
set shiftwidth=4
HTTP協(xié)議緩存：
文章使用Last Modified表示***修改時間，不禁止緩存。
header('Last Modified:Sat, 30 Oct 2010 13:21:21 GMT');
需要用戶登錄的頁面，禁止緩存。
- header('Cache-Control:max-age=0');
- header('Cache-Control:private');
HTTP協(xié)議編碼與mime：
web輸出一定要聲明編碼與mime。charset與分號之間要有一個空格。小寫utf-8還是大寫UTF-8，尚未找到文檔，待調(diào)研。
比如
- 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');
專有名詞大小寫：
在類、函數(shù)、文件名、目錄名等各種地方，不特殊對待專有名詞，不采用全大寫。
原因：專有名詞難以界定，比如HTML、CSS、CRUD。而且全大寫導致與駝峰沖突，比如頁面助手類，全大寫是HTMLHelper，不如HtmlHelper。
支持不特殊處理：
HTML是專有名詞，但mime中就使用Content-Type:text/html，而不是text/HTML。
例子：
采用UserDb.php，而不是UserDB.php。
原文：http://www.cnblogs.com/sink_cup/archive/2011/07/07/php_coding_standard.html
【編輯推薦】
