php编码规则(二)
3.7 声明块的定位
· 声明代码块需要对齐。
理由
· 清晰。
· 变量初始化的类似代码块应该列表。
· &应靠近类型，而不是变量名。
例如
var $mDate
var& $mrDate
var& $mrName
var $mName
$mDate = 0;
$mrDate = NULL;
$mrName = 0;
$mName = NULL;
3.8 每行语句应尽量短
除非这些语句有很密切的联系，否则每行只写一个语句。
在代码书写中，遵循以下原则：
（1）尽量保证程序语句一行就是一句，而不要让一行语句太长产生折行；
（2）尽量不要使一行的代码太长，一般控制在80个字符以内；
（3）如果一行代码太长，请使用类似 .= 的方式断行书写；
（4 对于执行数据库的sql语句操作，尽量不要在函数内写sql语句，而先用变量定义sql语句，然后在执行操作的函数中调用定义的变量；
例如：
$sql = "SELECT username,password,address,age,postcode FROM test_t ";
$sql .= " WHERE username='aaa'";
$res = mysql_query($sql);
3.9 短方法
方法代码要限制在一页内。
3.10记录所有的空语句
总是记录下for或者是while的空块语句，以便清楚的知道该段代码是漏掉了，还是故意不写的。
while ($dest++ = $src++)
; // VOID
3.11 不要采用缺省方法测试非零值
不要采用缺省值测试非零值，也就是使用：
if (FAIL != f())
比下面的方法好：
if (f())
即使 FAIL 可以含有 0 值 ，即PHP认为是false。但当某人决定用-1代替0作为失败返回值时，一个显式的测试就可以帮助你了。即使是比较值不会变化也应该使用显式的比较；
例如：
if (!($bufsize % strlen($str)))
应该写成：
if (($bufsize % strlen($str)) == 0)
以表示测试的数值（不是布尔）型。一个经常出问题的地方就是使用strcmp来测试一个字符等式，结果永远也不会等于缺省值。
非零测试采用基于缺省值的做法，那么其他函数或表达式就会受到以下的限制:
· 只能返回0表示失败，不能为/有其他的值。
· 命名以便让一个真(true)的返回值是绝对显然的，调用函数IsValid()而不是Checkvalid()。
3.12 布尔逻辑类型
遵循以下规则：
（1）不能使用0/1代替true/false，在PHP中，这是不相等的；
（2）不要使用非零的表达式、变量或者方法直接进行true/false判断，而必须使用严格的完整true/false判断；
如：不使用if ($a) 或者if (checka()) 而使用if (FALSE != $a)或者 if (FALSE != check())
大部分函数在FALSE的时候返回0，但是并非0值就代表TRUE，因而不要用1（TRUE，YES，诸如此类）等式检测一个布尔值，应该用0（FALSE，NO，诸如此类）的不等式来代替：
if (TRUE == func()) { ...
应该写成：
if (FALSE != func()) { ...
3.13 通常避免嵌入式的赋值
有时候会看到嵌入式赋值的语句，这样的结构可读性强并不强
while ($a != ($c = getchar()))
{
process the character
}
++和--操作符类似于赋值语句。因此，出于许多的目的，在使用函数的时候会产生副作用。使用嵌入式赋值提高运行时性能是可能的。无论怎样，程序员在使用嵌入式赋值语句时需要考虑在增长的速度和减少的可维护性两者间加以权衡。例如：
a = b + c;
d = a + r;
不要写成：
d = (a = b + c) + r;
虽然后者可以节省一个周期。但在长远来看，随着程序的维护费用渐渐增长，程序的编写者对代码渐渐遗忘，就会减少在成熟期的最优化所得。
4 注释
PHP中有两种注释方法，一种是使用//开始，另外一种是使用/**/。 //一般用来比较简短的注释。/**/则用在需要大量注释的代码中。
注 释要尽量清晰，扼要，同时要使得你的注释能被机器解析后，能以固定的格式放到手册中去。注释的种类主要包括：类的注释，属性注释、方法注释、变量注释以及 关键算法、重要代码实现等。所有的这些部分编织在一起，使得人们在以后的时间里能够准确的知道你干了什么，为什么这么做。
在注释时，有一些预定义的关键字用来表示方法的目的，作者等，这样那就不需要再起另外一套关键字或者说不懂中文而采用汉语拼音。
注释是增加程序可读性、可维护性的一种方法，而不是唯一方法。可读性和可维护性主要还是在代码命名，项目组织处提高。
4.1 预定义关键字
关键字 含义
Purpose 表示类、属性、方法要做些什么或者什么含义。
Package Name 类名
Author 作者
Modifications 修改记录（编号规则为“No”＋日期＋“－”＋序号）
Ref 参考
Method Name 方法名
Parameter 参数名（包括类型）
Return 返回值（包括类型）
Attribute/Variable Name 属性/变量名
Type 属性/变量类型
4.2 文件头注释
每个文件头部必须有统一的注释块，规则如下：
a．必须包含本文件的描述；
b．必须包含作者；
c．必须包含书写日期；
d．必须包含版本信息；
e．必须包含项目名称；
f．必须包含文件的名称；
g．重要的使用说明，如类的调用方法、注意事项等；
参考例子如下：
<?php
//
// +---------------------------------------------------------+
// | PHP version 4.0 |
// +---------------------------------------------------------+
// | Copyright (c) 1997-2001 The PHP Group |
// +---------------------------------------------------------+
// | This source file is subject to of the PHP license, |
// | that is bundled with this packafile LICENSE, and is |
// | available at through the world-web at |
// | http://www.php.net/license/2_02.txt. |
// | If you did not receive a copy of the and are unable to |
// | obtain it through the world-wide-web,end a note to |
// | license@php.net so we can mail you a immediately. |
// +---------------------------------------------------------+
// | Authors: Stig Bakken <ssb@fast.no> |
// | Tomas V.V.Cox <cox@idecnet.com> |
// | |
// +---------------------------------------------------------+
//
// $Id: Common.php,v 1.8.2.3 2001/11/13 01:26:48 ssb Exp $
（这个好犀利= =，原来是这样子的意思）
4.3 类的注释
每个类注释需要包含以下项目：
a．必须包含类的描述；
b．必须包含作者；
c．必须包含书写日期；
d．必须包含版本信息；
e．名称空间（可选）；
f. 参考（可选）；
参考例子如下：
/**
* @ Purpose:
* 访问数据库的类，以ODBC作为通用访问接口
* @Package Name: Database
* @Author: Forrest Gump gump@crtvu.edu.cn
* @Modifications:
* No20020523-100:
* odbc_fetch_into()参数位置第二和第三个位置调换
* John Johnson John@crtvu.edu.cn
* @ref: (参照)
*/
class Database
{
……
}
4.4 方法注释
每个类注释需要包含以下项目：
a．必须方法描述；
b．必须包含方法名称；
c．必须包含收入参数及类型；
d．必须包含输出参数及类型；
参考例子如下：
/**
* @Purpose:
* 执行一次查询
* @Method Name: query()
* @Parameter: string $queryStr SQL查询字符串
* @Return: mixed 查询返回值（结果集对象）
*/
function（$queryStr）{……}
4.5 属性注释
属性注释需要包含以下项目：
a．属性简短描述(必须)；
参考例子如下：
//用户名
var mDbUserName;
4.6 变量注释
变量注释需要包含以下项目：
a．变量简短描述(可选)；
变量在程序中出现次数是最多的，而且变量从其名字中应该能清楚看到其意义。对临时性变量、作用域较窄的变量可以省略注释，否则程序中将因为注释而变得非常臃肿。
参考例子如下：
//用户名
$user_name;
4.7 代码块注释
代码块注释仅在必要时才使用，例如程序关键算法等等。注释方法同变量和属性。
参考例子：
func f()
{
… …
//此处使用的是冒泡排序
… …
5 项目组织
此节主要在项目层次对涉及的文档，源码，说明等做出一些建议性方法。根据项目属性的不同，下面的部分可进行一些增删处理。
5.1 项目结构
·设计文档
主要是软件设计类图，包图，数据库结构，关键算法参考等
·项目说明
主要包含软件安装，使用说明，初始账号，注意事项等，以指导人们显示资源：
·源码
指能通过编译的或者运行正常的源码
·工程管理
包括需求文档，项目管理，Bug修复等。
除了上述文档外，可能含有其他形形色色的文档，到时按照项目定义的类型进行归档即可。
5.2 源码结构
此处主要介绍在开发企业网站或者小型网站中，常用的一些目录命名。当然如果你要开发的项目类似于百度或者新浪，你可能不会需要，因为那时会有专业的人员或者规范进行约束，方方面面都已经涉及。通常情况下，这些还是对你有帮助的。
一个完整独立的PHP项目目录结构如下：
/ 项目根目录
/manage(admin) 后台管理文件存放目录
/css css文件存放目录
/images 所有图片文件存放路径（在里面根据目录结构设立子目录）
/scripts 客户端js脚本存放目录
/tpl 网站模版文件存放目录
/uploads 上传文件目录
/inc(include) 全局函数包含文件目录
/cache 缓存目录
/install 安装程序目录
以上目录结构是通常的目录结构，根据具体应用的具体情况，可以考虑不用完全遵循，但是尽量做到规范化。
5.3 第三方开发包
对于在开发中引入的第三方开发包，如果可能，尽量将其放入单独目录进行管理，同时在项目文档中放入开发包的相关文档：帮助文档，原理介绍，项目地址等。
