美发店管理系统 编码规范及其代码.docx

美发店管理系统 编码规范及其代码.docx

《美发店管理系统 编码规范及其代码.docx》由会员分享，可在线阅读，更多相关《美发店管理系统 编码规范及其代码.docx（24页珍藏版）》请在冰豆网上搜索。

美发店管理系统编码规范及其代码

项目编号

200602006

文档编号

13

密级

内部

美发店管理系统编码规范及其代码说明

V1.0

****软件公司

评审日期：

****年*月**日

目录

1.导言4

1.1目的4

1.2范围4

1.3缩写说明4

1.4术语定义4

1.5引用标准5

1.6参考资料5

1.7版本更新信息5

2约定规则5

2.1给代码注释6

2.2让代码分段和缩进6

2.3行结束标志6

2.4在代码中使用空白6

2.5遵循30秒法则7

2.6每行只做一件事情7

2.7说明运行顺序7

2.8公共和保护接口最小化原则7

3命名规范8

3.1.1合适的命名8

3.1.2文件后缀9

3.1.3目录和文件命名9

3.1.4包的命名9

3.1.5类和接口命名10

3.1.6变量和属性命名10

3.1.7类的方法命名11

3.1.8函数命名12

3.1.9常量命名12

3.1.10局部变量命名13

3.1.11方法参数命名14

3.1.12数据表命名14

3.1.13数据表字段命名14

4注释规范15

4.1.1注释约定15

4.1.2文档注释16

4.1.3类和接口注释16

4.1.4成员函数注释17

4.1.5变量和属性注释19

4.1.6局部变量注释19

5格式规范20

5.1排版格式20

5.2代码样式21

5.2.1代码划分21

5.2.2变量替换21

5.2.3访问级别21

5.2.4条件格式22

5.2.5使用？

：

22

5.2.6Continue和break22

5.2.7布尔逻辑判断22

5.3文档化23

6开发规范24

6.1架构函数24

6.2封装业务方法24

6.3异常处理规范25

6.4测试维护规范25

6.5性能约束25

1.导言

1.1目的

该文档的目的是描述美发店管理系统项目的编码规范和对代码的说明，其主要内容包括：

●文件格式

●命名约定

●编码风格

●注释文档

●格式规范

●开发规划

本文档的预期的读者是：

●开发人员

●项目管理人员

●质量保证人员

1.2范围

该文档定义了本项目的代码编写规范，以及部分代码描述和所有代码的说明。

1.3缩写说明

UML

UnifiedModelingLanguage（统一建模语言）的缩写，是一个标准的建模语言。

php

HypertextPreprocessor的缩写，一种HTML内嵌式的语言，是一种在服务器端执行的嵌入HTML文档的脚本语言，语言的风格有类似于C语言，被广泛地运用。

MVC

Model-View-Control（模式－视图－控制）的缩写，表示一个三层的结构体系。

1.4术语定义

无

1.5引用标准

[1]《企业文档格式标准》

北京长江软件有限公司

[2]《PHP语言编写规范》

北京长江软件有限公司软件工程过程化组织

1.6参考资料

PHP编码规范[第一版]

PHPDocument使用说明规范

Java编码规范

PHP编程标准20001116FredrikKristiansen

1.7版本更新信息

本文档的更新记录如表Ｄ－１所示。

表D-1版本更新记录

修改编号

修改日期

修改后版本

修改位置

修改内容概述

000

2006.5.28

0.1

全部

初始发布版本

001

2006.6.10

1.0

6章

修改代码

2约定规则

2.1给代码注释

记住：

如果你的代码不值得注释，那么它就不值得保留。

当正确地使用了本文提到的注释标准和方针，就可以大幅度地提高代码质量。

2.2让代码分段和缩进

一种提高代码可读性的方法是给代码分段，换句话说，就是在代码块内让代码缩进。

所有在括号{和}之内的代码，构成一个块。

基本思想是，块内的代码都应统一地缩进去一个单位。

缩进由四个空格组成，禁止使用制表符TAB。

一行80字符以内是比较合适，在有些情况下，长点也可以,但最多为120个字符。

2.3行结束标志

行结束标志遵循Unix文本文件的约定，行必需以单个换行符（LF）结束。

换行符在文件中表示为10，或16进制的0x0A。

注：

不要使用苹果操作系统的回车（0x0D）或Windows电脑的回车换行组合如（0x0D,0x0A）。

2.4在代码中使用空白

在代码中加入几个空行，也叫空白，将代码分为一些小的、容易理解的部分，可以使它更加可读。

建议采用一个空行来分隔代码的逻辑组，例如控制结构，采用两个空行来分隔成员函数定义。

没有空白的代码很难读，很难理解。

2.5遵循30秒法则

其他的程序员应能在少于30秒钟的时间内完全理解你的成员函数，理解它做什么，为什么这样做，它是怎样做的。

如果他们做不到，说明你的代码太难维护，应加以改进。

30秒钟，明明白白。

一个好的经验法则是：

如果一个成员函数一个屏幕装不下，那么它就很可能太长了。

2.6每行只做一件事情

每一行代码只做一件事情。

在依赖于穿孔卡片的计算机发展的早期，想让一行代码完成尽量多的功能的想法是可以理解的。

若想在一行里做多件事情，就会使代码难于理解。

为什么要这样呢？

我们应使代码尽量容易理解，从而更容易维护和改进。

正如同一个成员函数应该并且只能做一件事一样，一行代码也只应做一件事情。

此外，应让代码在一个屏幕内可见。

也不应向右滚动编辑窗口来读取一整行代码，包括含有行内注释语句的代码。

2.7说明运行顺序

提高代码可读性的一个相当简单的方法是使用圆括号来说明PHP代码运行的准确顺序。

如果为了理解你的源码而必须了解编程语言的操作顺序，那么这说明源码中一定有什么重要的东西做的不对。

这大多是在AND或者OR其它几个比较关系处产生的逻辑比较上的问题。

注意：

如果你象前文所建议的那样，采用短小单独的命令行，那么就不会产生这个问题。

2.8公共和保护接口最小化原则

面向对象程序设计的基本点之一是最小化一个类的公共接口。

这样做有几个理由：

✧可学习性。

要了解如何使用一个类，只需了解它的公共接口即可。

公共接口越小，类越容易学习。

✧减少耦合。

当一个类的实例向另一个类的实例或者直接向这个类发送一条消息时，这两个类变得耦合起来。

最小化公共接口意味着将耦合的可能降到最低。

✧更大的灵活性。

这直接与耦合相联系。

一旦想改变一个公共接口的成员函数的实现方法，如你可能想修改成员函数的返回值，那么你很可能不得不修改所有调用了该成员函数的代码。

公共

接口越小，封装性就越大，代码的灵活性也越大。

✧尽力使公共接口最小化这一点明显地很值得你的努力，但通常不明显的是也应使被保护接口最

小化。

基本思想是，从一个子类的角度来看，它所有超类的被保护接口是公共的。

任何在被保护接口内的成员函数可被一个子类调用。

所以，出于与最小化公共接口同样的理由，应最小化类的被保护接口。

✧首先定义公共接口。

大多数有经验的开发者在开始编写类的代码之前就先定义类的公共接口。

第一，如果你不知道一个类要完成怎样的服务/行为，你仍有一些设计工作要做。

第二，这样做使这个类很快地初具雏形，以便其他有赖于该类的开发者在“真正的”类被开发出来以前至少可以用这个雏形开始工作。

第三，这种方法给你提供了一个初始框架，围绕着这个框架你构造类。

3命名规范

3.1.1合适的命名

命名是程序规划的核心。

古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可思议的力量。

只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。

总的来说，只有了解系统的程序员才能为系统取出最合适的名字。

如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出，一般人的推想也能在意料之中。

如果你发觉你的命名只有少量能和其对应事物相匹配的话，最好还是重新好好再看看你的设计吧。

3.1.2文件后缀

为了更好的识别文件类型和功能，对ThinkPHP框架中使用的php文件后缀名定义如下：

✧类和接口文件的后缀统一使用.class.php

✧其他文件的后缀统一用.php

3.1.3目录和文件命名

目录名和文件名命名应注意：

✧采用大小写结合的方式，并且首字母也大写；

✧一般不建议使用下划线‘_’，除非特殊需要；

✧不允许使用点‘.’，防止import错误；

✧不超过20个英文字符，不使用中文；

✧如果文件是一个类或者接口，那么应该和类名保持一致；

3.1.4包的命名

包在ThinkPHP中意义比较特殊，包的名称是由目录或者目录加文件名的方式组成，所以其相应的命名遵循目录和文件名的命名规范。

每个包名称之间用点号‘.’分隔开来。

如Think.Core.ActionThink.Util.ArrayList等。

全局包的名字用所在机构的Internet保留域名开头。

如：

Com.Sina，Org.Util等等；

（注意：

包的命名是需要和目录以及文件相对应的）

项目中包的命名方式是（也就代表了相应的目录结构）

域名＋项目名＋模块名＋类型＋类名

例如Com.Liu21st.Lab.Info.Action.UserActionCom.Liu21st.Lab.Info.Common.Filter

3.1.5类和接口命名

✧类和接口的命名规范同文件名的命名，并且类和接口的命名应该和该文件名一致（包括大小写）

✧尽量采用该领域的术语来命名类和接口。

如果用户称他们的“客户”为“顾客”，那么就采用术语

Customer来命名这个类，而不用Client。

许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。

✧避免使用长名字（最好不超过15个字母）。

虽然PhysicalOrVirtualProductOrService看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重新给它起个短一点的名字，比如象Offering。

✧在为类命名前首先要知道它是什么。

如果通过类名的提供的线索，你还是想不起这个类是什么的话，那么你的设计就还做的不够好。

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

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

✧有时后缀名是有用的，例如：

如果你的系统使用了代理（agent），那么就把某个部件命名为“下载代理”（DownloadAgent）用以真正的传送信息。

不要使用下划线“_”；

3.1.6变量和属性命名

所有变量和属性均使用完整的英文单词或缩写词方式命名，并附有中文注释。

其命名原则有：

✧使用可以准确说明变量/属性的完整的英文描述符。

例如，采用类似firstName，grandTotal或corporateCustomer这样的名字。

虽然象x1，y1或fn这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码以理解、维护和改进。

✧采用大小写混合，提高名字的可读性。

首字母一般应该采用小写字母。

✧尽量少用缩写，但如果需要使用，可以选择单词的头4个字母作为缩写。

如：

deptInfoValue，

mapActi,mapActiInst等等。

✧避免使用相似或者仅在大小写上有区别的名字。

例如，不应同时使用变量名persistentObject和

perSistentObject，以及anSqlDatabase和anSQLDatabase。

✧避免使用下划线作为名字的首末字母。

以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。

更重要的是，下划线经常造成麻烦而且难输入，所以尽量避免使用。

✧下划线“_”打头的变量和属性属于私有属性

✧以双下划线“”打头的变量和属性作为特殊变量使用时考虑（例如魔法变量）

3.1.7类的方法命名

成员函数名称的第一个单词常常采用一个有强烈动作色彩的动词。

如：

openAccount（）、printMailingLabel（）、createUser（）、delete（）等。

并且采用大小写结合的方式。

这种约定常常使人一看到成员函数的名称就能判断它的功能。

虽然这种约定要使开发者多做一些输入的工作，因为函数名常常较长，但是回报是提高代码的可理解性。

有时后缀名是有用的:

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

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

oKey键值。

例如：

retryMax表示最多重试次数，retryCnt表示当前重试次数。

∙有时前缀名是有用的：

ois含义为问一个关于某样事物的问题。

无论何时，当人们看到Is就会知道这是一个问题。

oget含义为取得一个数值。

oset含义为设定一个数值

例如：

isHitRetryLimit。

✧下划线“_”打头的方法属于私有方法

✧以双下划线“”打头的变量和属性作为魔法方法

3.1.8函数命名

函数命名应采用完整的英文描述符，全部使用小写，并且用下划线“_”连接。

虽然PHP对方法大小写没有区分，但是这样有助于帮助我们区分函数和（类）方法。

如file_get_contentimport

特例

单字母函数或者方法属于ThinkPHP特殊方法，通常是某些操作的简化定义，而且用大写，例如

ThinkPHP中的ADSL方法。

以开头的函数或者方法属于魔术方法或者特殊方法对待，其规则可以不受函数和方法命名约束。

第三方代码的命名原则上可以不受以上规则约束。

3.1.9常量命名

✧常量命名采用大写字母，用下划线“_”分割

✧尽量使用全称，如果需要缩写，用首4个字符

✧系统常量以THINK_打头，例如：

THINK_VERSION、THINK_PATH

✧类的常量以类的名称打头，例如DB_TYPE、LOG_WRITE_METHOD

✧模块常量以模块名称打头，例如INFO_TYPEUSER_ID

3.1.10局部变量命名

一般说来，命名局部变量遵循与命名变量和属性一样的约定，即使用完整的英文描述符，任何非开头的单词的第一个字母要大写。

但是为方便起见，对于如下几个特殊的局部变量类型，这个约定可以放宽：

✧循环计数器

✧异常

命名循环计数器

因为局部变量常用作循环计数器，并且它为C/C++所接受，所以在Java编程中，可以采用i、j、k、nIndex、nLoop作为循环计数器[GOS96]。

若采用这些名字作为循环计数器，要始终使用它们。

概括起来说，i、j、k、nIndex、nLoop作为计数器时，它们可以很快被输入，它们被广泛的接受。

命名异常对象

因为在PHP代码中异常处理也非常普遍，所以字母e作为一般的异常符被广泛地接受。

如果有多个异常同时出现，应该使用该类型异常全称的缩写表示。

catch（SQLExceptionsqlexception），一般情况下，每个应用模块应有个异常类。

如OA系统分为公文流转、用户机构、系统权限、档案管理等模块，这时应相应地有:

FlowException、OrgException、RightException、FileException等异常类，以便系统产生异常时，能从例外快速地定位问题发生在哪个模块。

3.1.11方法参数命名

✧如果是函数的参数或者非类的属性则不做特殊约定，按照变量和属性的命名规范执行；

✧如果是成员函数的参数，则首先使用和类的属性一致的命名；

例如

参数作为类的属性

functionsetLabel（$label）{

$this>label=$label;

}

其它类型参数

functioncreateVo（$typeId,$voName）{

}

3.1.12数据表命名

建议使用项目名_模块名_表名来作为数据表的完整名称，尽量使用英文全名，并且采用小写和下划线分割的规则，如果需要缩写，采用首4个字母，如

oa_info_userthink_common_file

3.1.13数据表字段命名

数据表的字段名称尽量采用规范的英文名称，全部采用小写格式，并且以下划线”_”分割。

如user_idroom_type

4注释规范

4.1.1注释约定

以/**开始，*/结束的文档注释；

以/*开始，以*/结束的C语言风格注释；以及以//开始，代码行末尾结束的单行注释。

下表是对各类注释语句建议用法的一个概括，也给出了几个例子。

注释语句类型

用法

示例

文档注释

在接口、类、成员函数和字段声明之前紧靠它们的位置用文档注释进行说明。

文档注释由phpdoc处理，为一个类生成外部注释文档。

/**

Customer（顾客）.顾客是指作为我们的服务及产品的销售对象的任何个人或组织。

@author流年

*/

C语言风格注释

采用C语言风格的注释语句将无用的代码注释掉。

保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。

/*

这部分代码已被它前面的代码替代，所以于1999年6月4日被B.Gustafsson注释掉。

如果两年之后仍未用这些代码，将其删除。

...（源代码）

*/

单行注释

在成员函数内部采用单注

释语句对业务逻辑、代码片段和临时变量声明进行说明。

//因为让利活动

//从1995年2月开始，

//所以给所有超过$1000的

//发货单5%的折扣。

4.1.2文档注释

每个文件都应该在开头部分使用文档注释，列出其类名、作用以及版权和版本信息。

可以参考ThinkPHP核心类库遵循的文档注释格式。

4.1.3类和接口注释

以下的信息应写在文档注释中紧靠类的定义的前面：

✧类的目的和作用。

开发者需要了解一个类的一般目的，以判断这个类是否满足他们的需求。

养成一个注释与类有关的任何好东西的习惯。

✧已知的问题。

如果一个类有任何突出的问题，应说明出来，让其他的开发者了解这个类的缺点

/难点。

此外，还应注明为什么不解决问题的原因。

✧类的开发/维护历史。

通常要包含一个历史记录表，列出日期、类的作者和修改概要。

这样做的目的是让进行维护的程序员了解过去曾对一个类所做的修改，是谁做了什么样的修改。

✧版权信息。

4.1.4成员函数注释

注释一个成员函数是为了函数更加可被理解，进而可维护和可扩展。

每一个PHP成员函数都应包含某种称之为“成员函数文档”的函数头。

这些函数头在源代码的前面，用来记录所有重要的有助于理解函数的信息。

这些信息包含但不仅仅局限于以下内容：

✧成员函数做什么以及它为什么做这个。

通过给一个成员函数加注释，让别人更加容易判断他们是否

可以复用代码。

注释出函数为什么做这个可以让其他人更容易将你的代码放到程序的上下文中去。

也使其他人更容易判断是否应该对你的某一段代码加以修改（有可能他要做的修改与你最初为什么要写这一段代码是相互冲突的）。

✧哪些参数必须传递给一个成员函数。

还必须说明，如果带参数，那么什么样的参数必须传给成员函数，以及成员函数将怎样使用它们。

这个信息使其他程序员了解应将怎样的信息传递给一个成员函数。

phpdoc@param标识便用于该目的。

✧成员函数返回什么。

如果成员函数有返回值，则应注释出来，这样可以使其他程序员正确地使用返回值/对象。

phpdoc@return标识便用于此目的。

✧已知的问题。

成员函数中的任何突出的问题都应说明，以便让其他程序开发者了解该成员函数的弱点和难点。

如果在一个类的多个成员函数中都存在着同样的问题，那么这个问题应该写在类的说明里。

✧任何由某个成员函数抛出的异常。

应说明成员函数抛出的所有异常，以便使其他程序员明白他们的代码应该捕获些什么。

phpdoc@exception标识便用于此目的。

✧如何在适当情况下调用成员函数的例子。

最简单的确定一段代码如何工作的方法是看一个例子。

考虑包含一到两个如何调用成员函数的例子。

✧可用的前提条件和后置条件。

前提条件是指一个成员函数可正确运行的限制条件；后置条件是指一个成员函数执行完以后的属性或声明。

前提条件和后置条件以多种方式说明了在编写成员函数过程中所做的假设，精确定义了一个成员函数的应用范围。

✧成员函数的开发/维护历史。

通常要包含一个历史记录表，列出日期、修改的作者和修改概要。

这样做的目的是让进行维护的程序员了解过去曾对一个成员函数所做的修改，是谁做了什么样的修改。

✧除成员函数注释以外，在成员函数内部还需加上注释语句来说明你的工作。

目的是使成员函数更易

理解、维护和增强。

✧内部注释应采用两种方式：

C语言风格的注释（/*和*/）和单行注释（//）。

正如上述所讨论的，应认真考虑给代码的业务逻辑采用一种风格的注释，给要注释掉的无用代码采用另外一种风格的注释。

对业务逻辑采用单行注释，因为它可用于整行注释和行末注释。

采用C语言风格的注释语句去掉无用的代码，因为这样仅用一个语句就可以容易地去掉几行代码。

此外，因为C语言风格的注释语句很象文档注释符。

它们之间的用法易混淆，这样会使代码的可理解性降低。

所以，应尽量减少使用它们。

在函数内，需要注释说明的地方：

✧控制结构。

说明每个控制结构，例如比较语句和循环。

你无须读完整个控制结构内的代码才判断它的功能，而仅需看看紧靠它之前的一到两行注释即可。

✧代码做了些什么以及为什么这样做。

通常你常能看懂一段代码做了什么，但对于那些不明显的代码，你很少能判断出它为什么要那样做。

例如，看完一行代码，你很容易地就可以断定它是在定单总额上打了5%的折扣。

这很容易。

不容易的是为什么要打这个折扣。

显然，肯定有一条商业法则说应打折扣，那么在代码中至少应该提到那条商业法则，这样才能使其他开发者理解你的代码为什么会是这样。

✧局部变量。

在一个成员函数内定义的每一个局部变量都应在它代码的所在行声明，并且应采用一个行内注释说明它的用法。

✧难或复杂的代码。

若发现不能或者没有时间重写代码，那么应将成员函数中的复杂代码详细地注释出来。

一般性的经验法则是，如果代码并非显而易见的，则应说明。

✧处理顺序。

如果代码中有的语句必须在一个特定的顺序下执行，则应保证将这一点注释出来。

没有

比下面更糟糕的事了：

你对一段代码做一点简单的改动，却发现它不工作，于是花了几个小时查找

问题，最后发现原来是搞错了代码的执行顺