1 文件格式
1.1 文件标记
不使用短标签;
只含有PHP代码的文件,在文件结尾省略“?>“,这是为了防止”?>“之后出现多余的空字符影响后面的代码。
1.2 文件和目录名
文件名和目录名只含字母、数字、下划线、中划线。使用驼峰命名;
//类统一采用DemoTest.class.php//接口统一采用DemoTest.interface.php//其他按照各自的方式demoTest.{style}.php
1.3 文件目录结构
通常一个完整独立的PHP项目的目录结构如下:
┗━━━app //独立的应用
┣━━━class //单个类文件,公用的类文件
┣━━━config/inc //配置文件目录
┣━━━data //数据文件目录
┣━━━doc //程序相关文档
┣━━━htdocs //document_root
┣━━━images //所有图片文件的路径(根据需要设立子目录)
┣━━━css //CSS文件
┣━━━js //JS脚本文件
┣━━━lib //公用类库
┣━━━template //模板文件
┣━━━temp //临时文件目录
┃ ┣━━━cache
┃ ┣━━━session
┃ ┣━━━template_c
┃ ┣━━━other
┣━━━upload //上传文件(按特定规则分目录存放)
┣━━━manage //后台管理文件存放目录
2 命名规范
2.1 变量命名
一个有效变量名有字母、数字、下划线开头,后面跟任意数量的字母、数字、下划线;
程序整体以驼峰法命名,以小写字母开头,如:
function displayName($name) { echo $name;}
PHP全局变量键值两边都有“_”,中间使用驼峰法命名,如:
$_GLOBAL['_beginTime_'];
普通变量整体采用驼峰法,以小写字母开头。对于一些常见变量按照约定命名,如:资源->$resource,布尔值->$flag;
函数名要有意义,也要尽量缩写,建议采用动词或动词加名词的命名方式,如:showMsg;
类中的属性变量遵守普通变量的命名规则。
2.2 类及接口命名
类
以大写字母开头;
多个单词组成的变量名,单词之间不用间隔,各个单词首字母大写;
类名与类文件保持一致;
程序中所有类名唯一;
抽象类应以Abstract开头。
接口
采取和类相同的命名规则;
尽量保持和实现它的类命名一致。
2.3 数据库命名
在数据库的命名中,一律不出现大写;
数据表
表名使用小写字母;
表名使用统一前缀;
对于多个单词组成的表名,使用“_”间隔;
表字段
全部使用小写字母命名;
多个单词不用下划线分割;
如果有必要,给常用字段加上表名首字母作为前缀;
避免使用关键字和保留字。
存储过程、触发器、event以及视图的命名在表的命名规则的基础上,遵循以下规则:
存储过程以proc_开头;
触发器以tri_开头;
Event调度以event_开头;
视图以view_开头。
2.4 习惯与约定
循环体中的临时变量采用“IN规则”,即在循环体重,可以使用$i、$j这样无意义的变量,通常用字母 I~N;
常用缩写
image->img
string->str
database->db
array->arr
count->cnt
temporary->temp或tmp
password->passwd或pwd
message->msg
魔术数字指直接写在代码里的具体数字,一般认为代码中不应该含有魔术数字,可以通过常量定义来避免这种情况
define(TAX, 1.05);$price_tax = TAX * price;
3 注释规范
3.1 程序注释
写在被注释代码前面,而不是后面。但对于单行语句,按照习惯可以把注释放在语句末尾;
对于大段注释,使用/* */格式,通常在文件和函数注释中使用,而代码内部统一使用 // 注释,因为其写起来简单;
注释不宜太多,大家能看懂的行不必注释。
/*** 初始化过程* @access public* @return void*/function init() { //列表文件不存在,则重新编译 if (!is_file(DATA_DIR . 'list.php')) { APP::clear(); //必须先删除缓存,防止数据不一致 APP::build(); }}
3.2 文件注释
文件注释通常放在整个PHP文件头部,其内容包括文件版权、作者、编写日期、版本号等重要信息。
文件注释遵循以下规则:
必须包含本程序的描述;
必须包含作者;
必须包含项目名称;
必须包含文件的名称;
可以包含书写日期;
可以包含版本信息;
可以包含重要的使用说明,如类的调用方法、注意事项等。
例如
/*** XX动漫论坛* * LICENSE* * 本代码来自于XX动漫论坛项目* @description 模型初始化,按需加载所需要的资源* @package __MODELINI__* @copyright Copyright(c) 2005-2111 阿里巴巴 Inc.* @author Ckelp ckelp@qq.com* @version 1.02* @modify 优化了search方法,提高效率。by:Ckelp*/
需要注意,文件一定要加上作者信息,这样有利于划分代码责任,同时方便代码阅读者联系作者。另外,版本号需要随着每次更新进行改动,并且加上modify注释,表明每次改动什么地方。
3.3 类/接口注释
类和接口的注释尽量简洁,一般情况,一个文件只包含一个类,如果文件注释已经足够详细,可以不用给类写注释。如果同时存在接口和接口的实现类,通常做法是仅在接口中进行注释。
3.4 方法和函数注释
方法和函数的注释写在前面,通常需要标明的信息有可见性、参数类型和返回值的类型,例如:
/*** 连接数据库* @param string $dbhost 数据库服务器地址* @param string $dbuser 数据库用户名* @param string $dbpw 数据库密码* @param string $dbname 数据库名* @param string $charset 数据库编码* @access public* @return void*/public function __construct($dbhost, $dbuser, $dbpw, $dbname = '', $charset = 'utf8') {//}
4 代码风格
4.1 缩进和空格
在编辑器中将tab设置为4个空格;
赋值变量是,等号左右留出空格;
使用大型IDE管理代码,例如在zend studio中,使用Ctrl+Shift+F对代码进行格式化。