PHP书写规范 PHP Coding Standard

通用原则：
1、语义化
看到名字，就知道意思。

2、通用前缀
is表示是否、get表示读、set表示写。is后面优先跟形容词，而不是名词，比如是否多语言文字，应使用is_multilingual，而不是is_multilanguage。

3、单数与复数
参考js的函数命名规则：getElementById、getElementsByTagName、getElementsByName。
例如：
取我的多个好友的名字，应使用getFriendsName，而不是getFriendNames或者getFriendName
取一个用户，是getUser
取多个用户，是getUsers

4、冗余后缀
尽量不使用data、list、info后缀。
比如，js的命名就很注意，使用getElementsByTagName而不是getElementsInfoByTagName。
应该使用getFriends或者getFriendsUserId，而不是getFriendsList；应该使用getUser，而不使用getUserInfo或者getUserData。
不过有时候很难避免，比如有2个函数，分别是取用户基本信息，和取用户详细信息。
取用户基本信息：昵称、头像URI，函数名getUserBasic还是getUserBasicInfo？函数名以形容词结尾感觉不合适，待讨论。
取用户详细信息：昵称、头像URI、签名、生日，函数名getUser没问题。

5、含义模糊的类名、文件名、目录名
每当使用common、util、functions、class、object、basic作为文件名时要慎重，由于这些词太通用，发展下去里面东西可能越来越多，变成垃圾箱。要给这些起一个准确的名字，比如要做字符串处理的类，可以叫StringLib.php，放在lib目录里。

6、lib、plugin与addon的区别
有些类、函数算做lib、plugin还是addon。待讨论。

类名：
大写字母开头，驼峰命名。一般使用名词，比如配置解析类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://veryhuo.com与http://VERYHUO.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。
与Java、C++不一致。待讨论。
类的成员变量、函数的形参、类实例化成一个对象，都遵守变量的命名规则。
原因：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

精彩内容，请点击下一页！