PHP书写规范(1)

PHP书写规范

作者：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后面优先跟形容词，而不是名词，比如是否多语言文字，应使用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。

历史原因可能无法改变，但我们能保证新的代码是严谨的，不要让自己成为历史原因。

类中的函数：

两个函数中间空一行。如果有时间的话，各个函数按英文字母排序，免得太混乱。

例如：

<ol class="dp-c">
<li class="alt"><span><span class="keyword">class</span><span> BlogModel  </span></span></li>
<li><span>{  </span></li>
<li class="alt">
<span>   </span><span class="keyword">public</span><span> </span><span class="keyword">function</span><span> addBlog()  </span>
</li>
<li><span>    {  </span></li>
<li class="alt"><span>    }    </span></li>
<li>
<span>    </span><span class="keyword">public</span><span> </span><span class="keyword">function</span><span> updateBlog()  </span>
</li>
<li class="alt"><span>    {  </span></li>
<li><span>    }  </span></li>
<li class="alt"><span>} </span></li>
</ol>

文件注释：

注释紧跟

格式按照PHPdoc的要求：

http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.author.pkg.html

<ol class="dp-c">
<li class="alt"><span><span><?php  </span></span></span></li>
<li>
<span class="comment">/** </span> </li>
<li class="alt"><span><span class="comment"> * blog的各种业务：添加、更新 </span> </span></li>
<li><span><span class="comment"> * @author sink </span> </span></li>
<li class="alt"><span><span class="comment"> * </span> </span></li>
<li><span><span class="comment"> */</span><span> </span></span></li>
<li class="alt">
<span class="keyword">class</span><span> BlogModel  </span>
</li>
<li><span>{  </span></li>
<li class="alt"><span> </span></li>
<li><span>}  </span></li>
<li class="alt"><span>?> </span></li>
</ol>

API注释：

一定要写输入参数，和输出格式。写清楚正确时输出什么，错误时输出什么。

否则别人无法使用。

1