PHP 程序编码规范:第 2 章 命名规范

2015-03-17 17:43:38 |  分类:PHP

 

2.1 变量命名

 

规范使用种书写方式:

 

1)Camel 命名规则(驼峰命名法)

标识符的首字母小写,而后面连接的单词的首字母都大写。

例如:$backColor

 

2) Linux C 命名规则

变量所有字母都使用小写,使用'_'作为每个词的分界。

变量名必须有一定的意义,并且意义准确。

例如:有一个变量用于保存图书的数目,可以命名为 number_of_book 或者 num_of_book。不建议使用 i,j,n 等,因为它没有意义。也不建议使用 number 或 book,因为意义不准确。

 

2.1.1 局部变量

所有变量都要预先声明,并注明其意义,在函数的首部定义所有的变量。不要使用一个声明一个;最好把每个变量的声明语句单独放到一行,并加上注释说明。所有变量按照字母排序。

 

$current_entry; // 当前选择项

$level;

$size;

// 缩进程度

// 表格大小

 

尽量减少全局变量的使用。不要让局部变量覆盖全局变量。变量所有字母都使用小写,使用'_'作为每个词的分界,定义的变量尽量做到见名识意

 

理由:通过这一途径,代码中变量的作用域是清晰的。所有的变量在代码中都看起来不同,容易辨认。

 

例如:

function handleError($errorNumber) {

           

$error osErr($errorNumber);

$time_of_error osErr->GetTimeOfError();

$error_processor osErr->GetErrorProcessor();

 

}

 

2.1.2 全局变量命名

全局变量使用 g 前缀。

例:

global $gLog;

global &$rgLog;

 

2.1.3 静态变量命名

静态变量使用 s 前缀,如: $s_value。

 

2.1.4 引用变量和函数返回引用

引用必须带‘r’前缀

理由:

使得类型不同的变量容易辨认,它可以确定哪个方法返回可更改对象,哪个方法返回不可更改对象。

如: $r_var。

function &rStatus() {};

 

2.1.5 临时变量命名

不要将在循环中频繁使用的临时变量如$i,$j 等用于其它用途。

 

2.1.6 方法中参数命名

参数的名字使用 Camel 命名方法(首字母小写),在首字符后的所有字都按照类命名规则首字符大写。

参数的名字应该是描述性的,参数的名字应该具有自描述性,也就是说参数的名称可以描述参数在大多数情况下的含义,参数的类型也是可以从参数的名字推断出来的。参数的名字是基于参数的含义而不是参数的类型。

理由:

可以区分方法中的一般变量。

你可以使用与类名相似的名称而不至于产生重名冲突。

例如:

class NameOneTwo {

    public function StartYourEngines(&$rSomeEngine, &$rAnotherEngine);

}

 

2.2 命名定义/ 全局常量

全局常量用'_'分隔每个单词。

理由:

  这是命名全局常量的传统。你要注意不要与其它的定义相冲突。

例如:

define("A_GLOBAL_CONSTANT", "Hello world!");

class Test {

public $mrStatus;

public function doSomething(&$rStatus) {};

public function &rStatus() {};

}

 

2.3 类命名

用 Pascal 命名规则,尽量谨慎的使用缩写,不要用下划线作类名单词连接符。

例如:用户评论类,应定义成 UserComment而不是User_Comment

在类中,方法放到属性定义前边、公用方法放到专用方法前边。

在为类命名前首先要知道它是什么。如果通过类名的提供的线索,你还是想不起这个类是什么的话,那么你的设计就还做的不够好。

超过三个词组成的混合名是容易造成系统各个实体间的混淆,再看看你的设计,尝试使用(CRC Session card)看看该命名所对应的实体是否有着那么多的功用。

对于派生类的命名应该避免带其父类名的诱惑,一个类的名字只与它自身有关,和它的父类叫什么无关。

有时后缀名是有用的,例如: 如果你的系统使用了代理(agent) 那么就把某个部件命名为“下载代理”,(DownloadAgent)用以真正的传送信息。

类使用英文的大小写来分隔单词,包括首个单词,所有单词的首字母大写,如 PageManager;

一般情况下,一个类对应到一个文件,当一些类关系紧密时,可以存放在一个文件中。存放类的文件采用 classname.class.php 方式命名。所有系统文件名均为小写。

 

 

2.3.1 接口命名原则

接口名字在类的原则上加前缀 I。

例如:IComponent (描述性名词)、ICustomAttributeProvider (名词短语)、IPersistable (形容词)等。

有的类, 必须用字母 I 作为类名前缀,而又不是一个接口。这是可以接受的,因为有的类名就是 I 开头的,

例如: IdentityStore。这种情况和接口的区别在于其第二个字母是小写的。

有的时候,定义完一个接口之后,也会定义一个类作为接口的标准实现。该类和该接口应该有类似的名字,唯一的区别就是接口名称前缀为字母 I。

如: IComponent 和它的标准实现 class Component {}。

 

2.3.2 Exception 命名原则

异常的命名以“Exception”为后缀。

 

2.3.3 类库命名

目前命名空间正在越来越广泛的被采用,以避免不同厂商和团体类库间的类名冲突。

当尚未采用命名空间的时候,为了避免类名冲突,一般的做法是在类名前加上独特的前缀,两个字符就可以了,当然多用一些会更好。

例如:

John Johnson 的数据结构类库可以用 Jj 做为前缀,如下:

class JjLinkList {

}

另一种折中方式是建立包含类库目录(事实上 Java 也是这么做的),以不通的目录代表不同的命名空间。

例如:

Microsoft 的数据库相关类库可以在:

/classes/com/Microsoft/Database/DbConn.php

Apache 的数据库相关类库可在:

/classes/org/apache/Database/DbConn.php

 

2.3.4 方法命名

采用 Camel 命名方法(首字母小写),在首字符后的所有字都按照类命名规则首字符大写。方法前面都要显示的标示方法的访问权private、protected、public。

理由:

使用所有不同规则的大部分人发现这是最好的折衷办法。

ps:这种方法和 PHP 并不像但是和 java 匹配,而又与 js/C#类似,程序界够乱套的。

例如:

class NameOneTwo {

public function doIt() {};

public function handleError() {};

}

 

2.3.5 方法/函数命名修饰

通常每个方法和函数都是执行一个动作的,所以对它们的命名应该清楚的说明它们是做什么的: 用checkForErrors()代替 errorCheck(),用 dumpDataToFile()代替 dataFile()。这么做也可以使功能和

数据成为更可区分的物体。

有时后缀名是有用的:

Max - 含义为某实体所能赋予的最大值。

Cnt - 一个运行中的计数变量的当前值。

Key - 键值。

例如: RetryMax 表示最多重试次数,RetryCnt 表示当前重试次数。

有时前缀名是有用的:

is - 含义为问一个关于某样事物的问题。无论何时,当人们看到 Is 就会知道这是一个问题。

get - 含义为取得一个数值。

set - 含义为设定一个数值

r - 小 r 前缀用于修饰返回引用的地方法与函数。

例如: $IsHitRetryLimit。

function &rStatus() {};

function doSomething(&$rStatus) {};

方法使用英文的大小写来分隔单词,命名建议使用动词+名词的方式,采用 Camel 命名方法(首字母小写),在首字符后的所有字都按照类命名规则首字符大写。

不要采用不常用的缩写,如 where2Go();

使用常用的缩写时,只大写首字母,如 getHtml()。

 

2.3.6 类属性命名

使用英文名词、动词,以写字母作为词的分隔,其他的字母均使用小写,单词的首个字母使用大写,不使用下划线,对于类属性为某个对象变量,则以字符串 Object 为后缀,例:

class UserAccount {

    public $tableName'';

    $databaseObject = null;

}

 

2.3.7 对象命名

使用类名称为变量前缀,所有字母都使用大写,以字符串_obj/Obj/Object 为后缀,

例:$input_obj new Input;

$inputObj new Input;

$inputObject new Input;

 

ps:经测试发现如果遇到比较长的类名的话精简变量名字是有必要的,前提是一眼就能看出名字的意义,变量过长的命名感觉导致书写困难,也影响程序可读性。

例:$front_obj JdFrontController::getInstance();

 

2.4 缩写词不要全部使用大写字母

无论如何,当遇到以下情况,你可以用首字母大写其余字母小写来代替全部使用大写字母的方法来表示缩写词。

使用: getHtmlStatistic.

不使用: getHTMLStatistic.

理由:

    当命名含有缩略词时,人们似乎有着非常不同的直觉。统一规定是最好,这样一来,命名的含义就完全可以预知了。

    举个 networkABCKey 的例子,注意 C 是应该是 ABC 里面的 C 还是 key 里面的 C,这个是很令人费解的。有些人不在意这些,其他人却很讨厌这样。所以你会在不同的代码里看到不同的规则,使得你不知道怎么去叫它。

例如:

class FluidOz // 不要写成 FluidOZ

class GetHtmlStatistic // 不要写成 GetHTMLStatistic

ps:不过有时也要是情况而定,如 PDO 类库本身全大写,那么 class MyPDO extends PDO{...} 也就说得过去了,如果 PDO 小写有可能起反作用,主要目的在于容易理解,而不是做样子。

 

2.5 函数命名

函数名字采用 C GNU 的惯例,所有的字母使用小写字母,使用'_'分割单词。

理由:

这样容易区分类方法?

ps:此条有待研究,函数与方法区分微小,人为扩大区分不会起到反作用么?调用的时候明显的->操作方还不够清晰么?

例如:

function some_bloody_function() { }

完成一组功能的函数放到一个文件中,存放函数的文件采用 name.func.php 命名。

 

 

 

 

 

2015-03-17 17:43:38 |  阅读( 0 ) |  评论( 0)
分享到: