Skip to content

Latest commit

 

History

History
218 lines (173 loc) · 6.56 KB

php.md

File metadata and controls

218 lines (173 loc) · 6.56 KB

PHP

文件/文件夹

文件根据项目差异允许使用__小驼峰__或__以下划线间隔的小写名称__，推荐使用后者，以较完整的词汇描述文件内容。新的词汇使用，请在部门内公开探讨。
所有php后缀应均为.php，且使用utf-8 (non-BOM)格式。

除此之外，对以下特殊类型的文件，要求特殊的文件后缀。
类：.class.php
配置：.conf.php
方法(集)：.func.php
流程性文件： .inc.php
钩子文件： .hook.php
模板文件： .tpl.php
语言文件： .lang.php

使用框架开发，请使用此框架要求的文件命名规范定义。

文件夹命名与文件要求统一。

代码结构

  • 缩进：所有代码缩进约定为4个空格，不可使用TAB键替换。

  • 大括号：左括号和右括号要求在编辑器内处于同一列，且在关键词下一行。该条件应用于所有if / else if / else / for / foreach / switch / do / while / try 等语句。

     if ($i > 1)
 {
     // ..statement..
 }
 else
 {
     // ..other statement..
 }

  • 运算符、小括号、空格、关键词和函数：

    1. 不同优先级运算符运算，不论是否需加括号，都应该补全括号表明运算顺序。
    2. 左括号“(”应与关键词或其他非括号字符之间有一个空格。
    3. 右括号“)”后非括号，点符号其他字符之间应有一个空格。
    4. 任何情况下，都应禁止出现仅有空格或TAB的空行，同时，任何程序行尾不能出现多余的TAB或空格。
    5. 关键词应全部使用小写。
    6. 函数命名应根据开发框架环境使用对应的命名方式，函数名后无空格。
    7. 代码区域应规划合理，任何超过15行的段落都应对应的断行并添加注释内容。
     $a = (($c / 10 * 12) + ($a * 11) + $b);
 $b = 0;
 for ($i = 0; $i <= $a; $i ++)
 {
     $b += $i;
 }

  • 引号：所有单纯的文本引用，必需使用单引号。对于文本中存在小于三个的变量拼接，可使用单引号与点符号，也可以使用双引号。大量字符拼接务必使用双引号，并使用花括号如下格式：
    严禁在双引号中不使用花括号直接引用数组或对象的内容。

     $str = "{$user}，这是{$project['name']}的文档。阅读并在第{$line->number}行填写…";

变量/常量

  • 变量命名： 由约定俗成的缩写和完整词义单词以及**下划线“_”**组成，如：

     $pre_column_name, $username, $translation_lang

    如使用临时变量，请在“$”后增加“_”（较大的临时数据请务必在使用结束后使用 unset 注销）如：

     $_time, $_temp, $_user

  • 所有自定义变量必需经过初始化后才可以使用。

     $b = array();             // 不可省略此句
 foreach ($array as $v)
 {
 	$b[] = $v;
 }

  • 在变量不可控的情况下，一定要使用 isset() 或 empty() 判断变量是否存在后再运算。特别是如 GET、COOKIE、数据库读取结果等变量时。
    禁止出现因此而引起的遍历或赋值报错，此错误大多会影响最终的结果。

  • 数组和多个变量赋值，要求等号的对齐：

     $username = 'ABC';
 $password = md5('123456');
 $lang     = 'zh-CN';
 
 $array    = array(
 	'username'    => $username,
 	'password'    => $password,
 	'lang'        => $lang,
 );

  • 常量要求由全大写单词及下划线组成，用于某个范围的常量应协商确定。

     PRODUCT_TYPE_HOTEL  DISTRICT_TYPE

数据库查询

简单的查询语句请在一行内完成。如涉及表关联、子表、多条件查询等，一律按照SQL标准格式化语句。
需要达到的要求是可逐层分析语句结构，如：

SELECT  o.`order`, o.`time`, o,`status`, o,`uid`, 
		u.`name`, p.`product` 
FROM `order` AS o
	LEFT JOIN `user` AS u ON o.`uid` = u.`id` 
	LEFT JOIN `product` AS p ON o.`product` = p.`id`
WHERE o.`uid` = :uid AND p.`name` LIKE :keyword
ORDER BY o.`id` DESC
LIMIT 0,10;

要点：

  • 关键词大写。
  • 库名、表名、字段名需要右 “`” 符号包裹（大键盘数字1前的符号）。
  • 独立子句要求缩进。
  • 尽量使用PDO的赋值解决方案，除非确认的被格式化的变量如(int)$_GET['id']，不要拼接SQL语句。

路径引用

所有对文件的路径的引用，都应该包含末尾的 "/"，且变量或常量命名应包含词汇path。
含 dir 的变量，仅表示文件夹名称。如下：

define('ROOT_PATH', dirname(__FILE__).'/');
$log_dir  = 'log';
$log_path = ROOT_PATH . $log_dir . '/';

代码重用

不吝啬类与函数的定义，凡是需求基本相同的代码，应整理并总结出函数，定义于对应相应的文件中；多个相关函数应整理并创建类。
代码重用，并不应用于钩子、可能要经常变更、复杂业务逻辑的代码。函数和类应该是特定功能或结果要求单一的。

注释

注释包括：行注释，块注释，业务注释，文件注释，调试注释：
行注释一般出现在代码后方，用于解释代码。如：算法解释、函数嵌套解释；
块注释则通常用于方法、类的阐述：

/** 
 * description...
 +-----------------------------------------
 * @access public
 * @param bool $a
 * @param string $b
 * @return void
 */

业务注释一般位于代码上方，与行注释相同，但多用于描述下面要进行的业务操作内容；

// 金额低于订单金额返回错误（业务注释）
if ($price < $order['price']) 
{
    $this -> error_code = 511;     // 错误代码511 （行注释）
    return false;
}

较长的业务可用“-”或“="补充长度，并用“v”和“^”标记起始。

// =======v======= 订单操作开始 =======v=======
// -------v------ 订单退款 ------v------
    statement..
// ------^------ 订单退款结束 ------^------
// =======^======= 订单操作结束 =======^=======

文件注释包括类注释和文件注释；

/**
 * description...
 +-----------------------------------------
 * @author author..
 * @category category..
 * @package package..
 * @version $Id$
 */

调试注释允许一直保存在文件中，规则如下：

/* debug:
statement..
//*/

注意末行为双注释，该注释的灵活性在于，当首行的“/*”变为“//*”时，中间的代码便成为可执行状态。

调试/日志

未完待续 ...