兄弟连php就业班72期学员项目_朝阳组_美丽说 mls_编码规范V1.0

NTSNTS 项目项目 PHPPHP 编码规范编码规范 文档编号 文档版本 1 0 文档属性 内部 作 者 汤青松 杜文星 窦晓婵 文档状态 草稿 正式发布 正在修改 已废弃 日 期 2013 12 19 word 文档模板 NTS 项目在线 第 2 页 共 15 页 文档修订记录文档修订记录 版本版本日期日期作者作者描述 注明修改的条款和内容 描述 注明修改的条款和内容 1 02013 12 19汤青松 杜文星 窦晓 婵 创建 word 文档模板 NTS 项目在线 第 3 页 共 15 页 目录目录 1文件命名文件命名 4 2源文件的编码规范源文件的编码规范 5 2 1开头注释 5 2 2引入语句 6 2 3缩进排版 6 3注释注释 6 3 1块注释 6 3 2文档注释 7 3 3数据库注释 8 4声明声明 8 4 1每行声明的变量数量 8 4 2类的声明 8 5语句语句 9 5 1简单的语句 9 5 2复合的语句 9 5 3IF与ELSE语句 9 6空白空白 10 6 1空行 10 7命名规范命名规范 10 7 1类 10 7 2类属性的命名 10 7 3函数 11 7 4变量 11 7 5常量 12 8编程惯例编程惯例 12 8 1变量赋值 12 8 2其他惯例 12 8 2 1运算符 前的表达式 12 word 文档模板 NTS 项目在线 第 4 页 共 15 页 9其它其它 13 1 文件命名文件命名 文件夹命名一般采用英文 长度一般不超过 20 个字符 命名采用小写字母 除特殊情况才使用中文拼音 不允许使用大写字母来命 可以减少 windows 和 linux 因文夹大小写原因引起的错误 一些常见的文件夹命名如 设计部分 images 存放图形文件 flashs 存放 Flash 文件 styles 存放 CSS 文件 scripts 存放 Javascript 脚本 medias 存放多媒体文件 docs 存放网站相关文档说明 程序部分 controllers 控制器 interfaces 控制器 models 存放模型文件 views 存放模版文件 如开发人员要建立目录请参考上述列出的命名 文件名称统一用小写的英文 字母 数字组合 页面表现层的模版文件命名规则为 动作 对像 html 或 动 作 类别 对像 html 例如 add user html 添加用户 add user score html 添加用户积分 add vipuser score html 添加高级会员用户积分 整体文件用 html 命名 页面局布文件用 tpl 命名 例如 word 文档模板 NTS 项目在线 第 5 页 共 15 页 PHP 文件必须以 php 结尾 如用 inc 结尾直接访问服务器不去解析的话会直接 把源码暴露出来 常用文件后缀参考 xxxxx inc php 包含文件 xxxx php 控制器文件 xxxxx conf php 配置文件 xxxxx func php 函数文件 XxxxxModel php 数据模型文件 XxxxxApi php 接口文件 2 源文件的编码规范源文件的编码规范 说明 当有选择性内容时 用红字标明的地方为必写项 2 1 开头注释开头注释 所有的源文件都应该在开头有一个注释 这样有利于 PHPDOC 功具生成相应 的文档 其中列出所属包 描述 版本信息 日期 作者 修改人后跟日期和版 权声明例如 简要说明 package demo 所属包 author liwenkai 作者 version V1 0 版本号 copyright Copyright c 2011 com 版权 modifierlixiaochen lixiaochen com 最后修改人 lastmodifide 2011 10 24 最后修改日期 参考截图 word 文档模板 NTS 项目在线 第 6 页 共 15 页 如果对文件进行了修改 应该在文件头中说明修改目的 修改日期 修改人 并变更文件的版本信息 如果修改问文件的一部分 则在文件中进行注释即可 并且标识出修改部分的起止位置 2 2 引入语句引入语句 网站系统会配置是否开启自动引入功能 如开启自动加载功能 开发人员不 需要手工引入类 直接 new 所用的类名就可以命名规则 类名 如 user new Json 2 3 缩进排版缩进排版 4 个空格常被作为缩进排版的一个单位 缩进的确切解释并未详细指定 空格 vs 制表符 一个制表符等于 8 个空格 而非 4 个 所以在某些编辑器中 需要 特别指定一下制表符的长度为 4 UltraEdit 而在某些编辑器中 会将制表符 转换为空格 参考截图 3 注释注释 3 1 块注释块注释 块注释通常用于提供对文件 方法 数据结构和算法的描述 块注释被置于 每个文件的开始处以及每个方法之前 它们也可以被用于其他地方 比如方法内 部 在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式 块注释之首应该有一个空行 用于把块注释和代码分割开来 比如 这里是块注释 类方法的注释 说明功能 参数 返回值 如有歧义应加用法说明 例如 addCode id sc 用户添加积分 word 文档模板 NTS 项目在线 第 7 页 共 15 页 param int id 用户的 ID 参数说明 param int sc 要加分数 参数说明 return boole xxx 返回成功或失败 public function addCode id sc do some thing 参考截图 3 2 文档注释文档注释 文档注释描述 php 的类 构造器 方法 以及字段 field 每个文档注释都 会被置于注释定界符 之中 一个注释对应一个类或成员 该注释应位于声 明之前 说明这个类的一些 class Example 注意顶层 top level 的类是不缩进的 而其成员是缩进的 描述类的文档注 释的第一行 不需缩进 随后的文档注释每行都缩进 1 格 使星号纵向对齐 成员 包括构造函数在内 其文档注释的第一行缩进 4 格 随后每行都缩进 5 格 若你想给出有关类 变量或方法的信息 而这些信息又不适合写在文档中 则可使用实现块注释 见 3 1 例如 有关一个类实现的细节 应放入紧跟在类声 明后面的实现块注释中 而不是放在文档注释中 文档注释不能放在一个方法或构造器的定义块中 因为程序会将位于文档注 释之后的第一个声明与其相关联 参考截图 word 文档模板 NTS 项目在线 第 8 页 共 15 页 3 3 数据库注释数据库注释 除主键外 其它字段都应该给出相应的注释以方便开发人员的查询 如有状 态位请加以说明例如 tag varchar 30 NOT NULL default COMMENT 群组标签 vister varchar 90 NOT NULL default COMMENT 群组访客 1 2 3 参考截图 4 声明声明 4 1 每行声明的变量数量每行声明的变量数量 推荐一行一个声明 因为这样以利于写注释 亦即 level 0 缩进的程度 size 1 由制表符决定 要优于 level size 不要将不同类型变量的声明放在同一行 例如 foo fooarray 错误 注意 上面的例子中 在类型和标识符之间放了一个空格 另一种被允许的 替代方式是使用制表符 level 缩进的程度 size 由制表符决定 currentEntry 通常选择制表符作为缩进的标准 参考截图 word 文档模板 NTS 项目在线 第 9 页 共 15 页 4 2 类的声明类的声明 当编写类时 应该遵守以下格式规则 在方法名与其参数列表之前的左括号 间不要有空格 左大括号 位于声明语句同行的末尾 右大括号 另起一行 与相应的声明语句对齐 除非是一个空语句 应紧跟在 之后 参考截图 class Sample extends Object public ivar1 public ivar2 function Sample int i int j ivar1 i ivar 2 j function emptyMethod 方法与方法之间以空行分隔 参考截图 word 文档模板 NTS 项目在线 第 10 页 共 15 页 5 语句语句 5 1 简单的语句简单的语句 每行至多包含一条语句 例如 argv 正确的 argc 正确的 argv argc 错误的 5 2 复合的语句复合的语句 复合语句是包含在大括号中的语句序列 形如 语句 例如下面各段 被括其中的语句应该较之复合语句缩进一个层次 左大括号 应位于复合语句起始行的行尾 右大括号 应另起一行并与复 合语句首行对齐 大括号可以被用于所有语句 包括单个语句 只要这些语句是诸如 if else 或 for 控制结构的一部分 这样便于添加语句而无需担心由于忘了加括号而引入 bug 5 3 if 与与 else 语句语句 注意 if 语句总是用 和 括起来 避免使用如下容易引起错误的格式 if condition 避免这种写法 他忽略了 statement 只要可以描述清楚各分支之间的关系 在哪里写注释均可 6 空白空白 6 1 空行空行 空行将逻辑相关的代码段分隔开 以提高可读性 下列情况应该总是使用两个空行 一个源文件的两个片段 section 之间 类声明声明之间 下列情况应该总是使用一个空行 两个方法之间 word 文档模板 NTS 项目在线 第 11 页 共 15 页 方法内的局部变量和方法的第一条语句之间 块注释或单行注释之前 一个方法内的两个逻辑段之间 用以提高可读性 7 命名规范命名规范 7 1 类类 类名是个一名词 采用大小写混合的方式 每个单词的首字母大写 尽量使 你的类名简洁而富于描述 使用完整单词 避免缩写词 除非该缩写词被更广泛使 用 像 URL HTML class Raster class ImageSprite 在为类 class 命名前首先要知道类的功能 如果通过类名的提供的线索 不能准确反映类的功能 那么 命名就是失败的 超过三个词组成的混合名是容易造成系统各个实体间的混淆 尝试使用 CRC Session card 看看该命名所对应的实体是否有着那么多的功用 对于派生类的命名应该避免带其父类名的诱惑 一个类的名字只与它自身有 关 和它的父类无关 7 2 类属性的命名类属性的命名 类属性的命名以变量类型字母小写开头 例如 class NameOneTwo public iScore public aInfo public sMrName 参考截图 word 文档模板 NTS 项目在线 第 12 页 共 15 页 7 3 函数函数 方法名是一个动词 采用大小写混合的方式 第一个单词的首字母小写 其 后单词的首字母大写 function run function runFast function getBackground 通常每个方法都是执行一个动作的 所以对它的命名应该清楚的说明它是做 什么的 用 checkForErrors 代替 errorCheck 用 dumpDataToFile 代替 dataFile 这么做也可以使功能和数据成为更可区分的物体 有时后缀名是有用的 Max 含义为某实体所能赋予的最大值 Cnt 一个运行中的计数变量的当前值 Key 键值 例如 retryMax 表示最多重试次数 retryCnt 表示当前重试次数 有时前缀名是有用的 is 含义为问一个关于某样事物的问题 无论何时 当人们看到 Is 就会知道 这是一个问题 get 含义为取得一个数值 set 含义为设定一个数值 例如 isHitRetryLimit 参考截图 word 文档模板 NTS 项目在线 第 13 页 共 15 页 7 4 变量变量 PHP 所接收到的变量都必须要经过处理 变量名应采用小写命名方式 如出现多词组的用下划线做为连接符 变量名 不应以下划线或美元符号开头 尽管这在语法上是允许的 变量名应简短且富于描述 变量名的选用应该易于记忆 即 能够指出其用 途 尽量避免单个字符的变量名 除非是一次性的临时变量 临时变量通常被取 名为 i j k m 和 n 它们一般用于整型 c d e 它们一般用于字符型 c i myWidth 7 5 常量常量 类常量和 ANSI 常量的声明 应该全部大写 单词间用下划线隔开 尽量避 免 ANSI 常量 容易引起错误 static final int MIN WIDTH 4 static final int MAX WIDTH 999 static final int GET THE CPU 1 参考截图 word 文档模板 NTS 项目在线 第 14 页 共 15 页 8 编程惯例编程惯例 8 1 变量赋值变量赋值 避免在一个语句中给多个变量赋相同的值 它很难读懂 例如 fooBar fChar barFoo lchar c 错误 不要将赋值运算符用在容易与相等关系运算符混淆的地方 例如 if c d 错误 应该写成 if c d 0 不要使用内嵌 embedded 赋值运算符试图提高运行时的效率 这是编译器的 工作 例如 d a b c r 错误 应该写成 a b c d a r 8 2 其他惯例其他惯例 8 2 1运算符运算符 前的表达式前的表