卡布达研发团队

# PHP 开发规范

# 命名规范

  1. 【强制】代码中的命名均不能以下划线开始，也不能以下划线或美元符号结束

    • 反例：$name / $name$ / $name /$name__

  2. 【强制】代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式

    • 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式 也要避免采用。
    • 正例：alibaba / taobao / shanxi   等国际通用的名称，可视同英文。
    • 反例：DaZhePromotion [打折] / getPingfenByName() [评分] / $某变量 = 3

  3. 【强制】类名使用 UpperCamelCase 风格

    • 正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
    • 反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

  4. 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从 驼峰形式。

    • 正例：localValue / getHttpMessage() / inputUserId
// 获取某个用户的信息，方法名前缀使用get/变量名后缀使用info
getUserInfo() / $userInfo

// 获取多个用户的信息，方法名前缀使用list/变量名后缀使用list
listUserInfo() / $userList

// 统计用户数据，方法名前缀使用count/变量名后缀使用count
countUser() / $userCount

// 新增用户信息，方法名前缀使用create
createUser()

// 删除用户信息，方法名前缀使用delete
deleteUser()

// 修改用户信息
updateUser()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  1. 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

    • 正例：MAX_STOCK_COUNT
    • 反例：MAX_COUNT

  2. 【推荐】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词 组合来表达其意。

    • 正例：$finishCount
    • 反例：$a

  3. 【推荐】如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。

    • 正例：class OrderFactory / LoginProxy

# 代码格式

  1. 【强制】左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格；而左大 括号前需要空格。

    • 正例：if(a == b)
    • 反例：if( a == b )

  2. 【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。

  3. 【强制】任何二目、三目运算符的左右两边都需要加一个空格。

    • 说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

  4. 【强制】注释的双斜线与注释内容之间有且仅有一个空格。

    • 正例：// 这是示例注释，请注意在双斜线之后有一个空格
    • String ygb = new String();

  5. 【强制】单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：

    • 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
    • 运算符与下文一起换行。
    • 方法调用中的多个参数需要换行时，在逗号后进行。
    • 反例：// 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行 method(args1, args2, args3, ..., argsX);

  6. 【强制】方法参数在定义和传入时，多个参数逗号后边必须加空格。

    • 正例：method(args1, args2, args3);

  7. 【强制】需求完成之后，使用 phpstorm 格式化代码功能对代码风格进行统一管理，使用 phpstorm 默认的代码风格，windows 快捷键 ctrl + alt + L, mac 快捷键 option + command + L（强制执行）

  8. 【推荐】单个方法的总行数不超过 100 行

    • 说明：包括方法签名、结束右大括号、方法内代码、注释、空行、回车及任何不可见字符的总 行数不超过 100 行。
    • 正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码 更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。

  9. 【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

    • 说明：任何情形，没有必要插入多个空行进行隔开。

# 控制语句

  1. 【强制】在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程 序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且 放在最后，即使空代码。

  2. 【强制】在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码，严禁采用 单行的编码方式：if (condition) statements;

  3. 【强制】在高并发场景中，避免使用”等于”判断作为中断或退出的条件。

    • 说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间 判断条件来代替。
    • 反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变 成了负数，这样的话，活动无法终止。

  4. 【强制】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、 获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体外）。

  5. 【推荐】表达异常的分支时，少用 if-else 方式，这种方式可以改写成：

    • if (condition) {  ...  return obj;  } // 接着写 else 的业务逻辑代码;
    • 说明：如果非得使用 if()...else if()...else...方式表达逻辑，【强制】避免后续代码维 护困难，请勿超过 3 层。

  6. 【推荐】除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将 复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。

    • 说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么 样的条件执                  行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？
    • 正例： $boolean = (file_open($fileName, "w") != null) && (...) || (...);   if ($boolean) {  ...  }
    • 反例：if ((file.open(fileName, "w") != null) && (...) || (...)) {  ...  }

# 注释规约

  1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用 // xxx 方式。

  2. 【强制】所有的类都必须添加创建者和创建日期。

  3. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释 使用/* */注释，注意与代码对齐。

  4. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑 等的修改。

  5. 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

    • 说明：：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没 有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。

  6. 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含 义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同 天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看 的，使其能够快速接替自己的工作。

  7. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的 一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

# 交互标准

  1. 接收参数或返回参数，命名格式必须用下划线链接。

正例：

[
'total_money' :100,
'total_price':100,
]
1
2
3
4

  1. 当某个接口接收参数，或返回数据格式发生改变时，通过用版本号来兼容新旧业务。

    • 正例：www.test.com/api/v1/jingxuan/order_goods_list
    • 当接口参数发生改变或返回数据格式发生改变，保留原接口，并在原接口基础上升级版本
    • www.test.com/api/v2/jingxuan/order_goods_list

  2. pc 和小程序接口不再对使用端区分，相同业务共用一个接口。

# 其它

  1. 【推荐】及时清理不再使用的代码段或配置信息。

框架

← Nodejs 开发规范 →