共计 5991 个字符,预计需要花费 15 分钟才能阅读完成。
很多新手学习了 PHP,程序也简单的写了一两个,但是 PHP 程序的内容真的是很乱,没有一点的规范,虽然程序不会报错,但是对于将来开发程序来说,这样并不是一个好的习惯,那么,怎么样才算是正确的 PHP 语言书写格式呢?我们参考官方资料,给大家解读。
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 的要求:
<?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/?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 短标签:
使用,不使用短标签。因为与 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(!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
数组小括号换行:
有争议无定论,待讨论。
$user = array(
"id" => "123",
"name" => "user1",
"email" => "a@example.com",
)
1 维数组内部不换行? 待讨论。
如
$users_id = array(’23’,’12’,’24’);
数组最后的逗号:
数组每一行最后要有逗号,这样方便以后添加。不过前端 JSON 最后不能有逗号,否则有的浏览器不支持,待讨论。
比如
$user = array(
'id' => '123',
'name' => 'user1', // 正确
);
$user = array(
'id' => '123',
'name' => 'user1' // 错误
);
单引号与双引号:
优先使用单引号,当需要转义时使用双引号。这与 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 个空格,一定不要出现 5 个空格或者 11 个空格。
eclipse——》General——》Editor——》Text Editors——》show whitespace characters
vim ~/.vimrc
set expandtab
set softtabstop=4
set shiftwidth=4
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:
web 输出一定要声明编码与 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。