Coding-Specification

2017-01-23

php

编写目的

为了更好的提高技术部的工作效率，保证开发的有效性和合理性，并可最大程度的提高程序代码的可读性和可重复利用性，指定此规范。开发团队根据自己的实际情况，可以对本规范进行补充或裁减。本规则会不断的进行适当的改进，以适应最新的开发环境。

程序员可以了解任何代码，弄清程序的状况；
新人可以很快的适应环境；
防止新接触PHP的人出于节省时间的需要，自创一套风格并养成终生的习惯；
防止新接触PHP的人一次次的犯同样的错误；
在一致的环境下，人们可以减少犯错的机会；

整体要求

技术部php开发规范将参照PEAR的规范，基本采用PEAR指定的规范，在其基础上增加、修改或删除部分适合具体开发环境的规范
本规范包含了PHP开发时程序编码中命名规范、代码缩进规则、控制结构、函数调用、函数定义、注释等方面的规则。

编码规范

一、命名规范

1、普通变量命名遵循以下规则
- 所有字母都使用小写
- 对于一个变量使用多个单词的，使用驼峰结构命名，即以小写字母开头，从第二个单词开始，每个单词的第一个字母大写
2、PHP中类命名遵循以下规则
- 以大写字母开头
- 多个单词组成的变量名，单词之间不用间隔，各个单词首字母大写
- 例子：class MyClass 或 class DbOracle等
3、方法或函数命名遵循以下规则
- 首字母小写
- 多个单词间不使用间隔，除第一个单词外，其他单词首字母大写
- function myFunction() 或 function myDbOracle()等
4、数据库字段命名遵循以下规范：
- 全部使用小写；
- 多个单词间使用_间隔。

二、书写规范

1、在书写代码的时候，必须注意代码的缩进规则，我们规定代码缩进规则如下：
- 使用4个空格作为缩进，而不使用tab缩进（对于ultraedit，可以进行预先设置）
2、大括号{}书写规则
- 在程序中进行结构控制代码编写，如if、for、while、switch等结构，大括号传统的有两种书写习惯，分别如下：
- { 直接跟在控制语句之后，不换行，如：
  1
  2
  3
  for($i = 0; $i < $count; $i++) {
  echo 'test';
  }
- { 在控制语句下一行，如：
  1
  2
  3
  4
  for($i = 0; $i < $count; $i++) {
  {
  echo 'test';
  }

其中，第一种是PEAR建议的方式，但是从实际书写中来讲，这并不影响程序的规范和影响用phpdoc实现文档，所以可以根据个人习惯来采用上面的两种方式，但是要求在同一个程序中，只使用其中一种，以免造成阅读的不方便。

3、小括号、关键词和函数遵循以下规则：
- 小括号和函数名间没有空格；如$test = date(“ymdhis”)；
- 除非必要，不要在Return返回语句中使用小括号。如Return $a；
4、在程序中=符号的书写遵循以下规则：
- 在=符号的两侧，均需留出一个空格；如 $a = $b 、$a = ‘test’等；
- 在=符号与!、=、<、>等符号相邻时，不需留一个空格；如 if ( $a == $b ) 、if ( $a != $b ) 等；
5、对于控制结构的书写遵循以下规则：
- switch结构中必须要有default块；
- 在 for 和 wiile 的循环使用中，要警惕 continue 、 break 的使用，避免产生类似 goto 的问题；
6、如果要在类里面编写构造函数，必须遵循以下规则：
- 不能在构造函数中有太多实际操作，顶多用来初始化一些值和变量；
- 不能在构造函数中因为使用操作而返回false或者错误，因为在声明和实例化一个对象的时候，是不能返回错误的；
7、IF语句遵循以下规则：
- 不能使用 1/0 代替 true/false，在 PHP 中，这是不相等的；
- 不要使用非零的表达式、变量或者方法直接进行 true/false 判断，而必须使用严格的完整 true/false 判断；
  
  如：不使用 if ( $a ) 或者 if ( checka() ) 而使用 if ( FALSE != $a ) 或者 if ( FALSE != check() )
8、引号
- PHP中单引号和双引号具有不同的含义，最大的几项区别如下：
  1. 单引号中，任何变量($var)、特殊转义字符(如“\t \r \n”等)不会被解析，因此PHP的解析速度更快，转义字符仅仅支持“\’”和“\\”这样对单引号和反斜杠本身的转义；
  2. 双引号中，变量(\$var)值会代入字符串中，特殊转义字符也会被解析成特定的单个字符，还有一些专门针对上述两项特性的特殊功能性转义，例如“\\$”和“{$array[‘key’]}。这样虽然程序编写更加方便，但同时PHP的解析也很慢；
  3. 数组中，如果下标不是整型，而是字符串类型，请务必用单引号将下标括起，正确的写法为\$array[‘key’]，而不是$array[key]，因为不正确的写法会使PHP解析器认为key是一个常量，进而先判断常量是否存在，不存在时才以“key”作为下标带入表达式中，同时出发错误事件，产生一条Notice级错误。
    因此，在绝大多数可以使用单引号的场合，禁止使用双引号。依据上述分析，可以或必须使用单引号的情况包括但不限于下述：
    1.字符串为固定值，不包含“\t”等特殊转义字符；2.数组的固定下标，例如\$array[‘key’]表达式中不需要带入变量，例如\$string = ‘test’;，而非\$string = “test$var”；

三、注释

程序中变量或者语句的注释遵循以下原则：
- 写在变量或者语句的前面一行，而不写在同行或者后面；
- 注释采用/ /的方式；
- 每个函数前面要包含一个注释块。内容包括函数功能简述，输入/输出参数，预期的返回值，出错代码定义；
- 注释完整规范；
- 把已经注释掉的代码删除，或者注明这些已经注释掉的代码仍然保留在源码中的特殊原因。