phpDevelopDoc/CodeStyle.md

代码风格规约

命名风格

[强制] 变量命名需要以驼峰方式

为了保证变量命名可清晰辨认,在定义变量时,需要以驼峰方式进行命名.

驼峰命名规范为,单个单词均使用小写字母,多个单词之间首单词首字母使用小写字母,后续单词中首字母使用大写字母.

在变量命名中,请 [推荐] 给变量进行归类命名,例如 (数据库获取用户结果)$resultUser/(数据库获取书籍结果)$resultBook，(数组存储书本)$arrayBook/(数组存储Cookie)$arrayCookie.

• 允许的命名
  • $resultData,$arrayJson,$getDataForAdmin等
• 非法的命名
  • $ResultData,$RESULTDATA,$resultdata等

[强制] 方法命名以驼峰方式

为了保证方法命名可清晰辨认,在定义方法时,需要以驼峰方式进行命名.

驼峰命名规范为,单个单词均使用小写字母,多个单词之间首单词首字母使用小写字母,后续单词中首字母使用大写字母.

在方法命名中,需要根据成员变量合理构建所需的方法,进行方法封装,设计成员变量的读取与成员变量的写入,例如: 定义用户年龄的成员变量 $dataAge ,进行变量封装,将 $dataAge 采用 private 进行封装,定义 public function setDataAge(int $age) 与 public function getDataAge*() 分别进行成员变量 $dataAge 的写入与读取.

// 允许的命名风格
public function getArrayMerge() {}
public function setDataAge(int $age) {}

// 非法的命名
public function SetDataAge() {}
public function GETMERGE() {}

[强制] 常量,枚举命名必须全部字符为大写

对于(静态)常量或枚举常量,需要保证变量的命名为全大写,以特别明确分清楚大写内容为常量或枚举.

[推荐] 对于常量,无特殊要求须设置为静态常量,方便调用及处理.

// 动态常量举例
const $MAXSIZE;
// 静态常量举例
const static $MAXSIZE;

// 允许的命名风格
const static $MAXSIZE = 100;
const $DOMAIN = "https://www.x-lf.com/";
public const static string $VERSION = "1.19.2";

// 非法的命名风格
const static $MaxSize = 100;
const $domain = "https://www.x-lf.com/";
const static $doWork = 1;
public const static string $Version = "1.19.2";

[强制] Json接口编写规范

在接口名字定义时,均采用驼峰命名方案进行命名操作,以下是一个标准Json格式定义,请开发者编写时务必遵从开发规定.

• output: 输出状态基本信息(当方法实现成功时候务必返回 Success ,若发生其他错误请返回对应字符注意:如果该字段由多个单词组成中间不留空格均使用首字母大写替代)
  • 强制写法举例: not founded this user -> NotFoundedThisUser
  • 错误写法: not founded this user -> notFoundedThisUser/NOTFOUNDEDTHISUSER/not_founded_this_user
• status: 状态码,当前状态码,状态码由开发者团队协商决定,非HTTP请求返回码
• code: HTTP请求状态码(例如:200 Success,403 Not Founded)
• message: 具体错误的描述(请填写string值,例如:没有找到这个用户)
• data: 写明具体需要返回的内容,即参数

{
    "output": "DemoFunction",
    "status": 12,
    "code": 200,
    "message": "没有找到这个用户",
    "data": {
        // Data
    }
}

代码风格

[强制] 构建形参必须标明类型

避免方法中错误传参导致执行错误信息,在方法构建时,若设计形参构建,务必标明类型

// 允许风格
function setName(string $getName): void
{
    $this.name = $getName;
}

// 非法风格
function setName($getName): void
{
    $this.name = $getName;
}

[推荐] 对于常量,无特殊要求须设置为静态常量

对于常量,无特殊要求须设置为静态常量,方便调用及处理.

// 动态常量举例
const $MAXSIZE = 100;
public const int $MAXSIZE;
// 静态常量举例
const static $MAXSIZE = 100;
public const static int $MAXSIZE;

静态变量中,不推荐初始化(静态)常量后再赋予初值,建议一次性完整赋值.

但对于成员常量中,可使用构造方法对常量进行赋值.

往往在类中,常量由对应写法中直接进行构建,而非永久初始化定义

// 不推荐写法
const static $MAXSIZE;
$MAXSIZEE = 100;

// 推荐写法
class feature {
    public const static int $MAXSIZE;
    
    public function __construct() 
    {
        $this.MAXSIZE = 100;
    }
    
    /* 参考写法
    public function __construct(int $maxSize) 
    {
    	$this.MAXSIZE = $maxSize;
    }
    */
}

[参考] 注意成员变量构建可见范围

在一般开发中,若无特征说明该成员变量的用途,不推荐将其设置为 public 范围,避免造成多成员变量导致参数使用混乱,若需要对该成员变量进行增删改查,请使用封装进行操作,对于初始化变量,建议在构造方法赋予初值或赋予空值.

// 推荐写法
class feature() {
    protected int $value = 12;
    private string $data;
    private const static string $struck;
    
    public function __construct() 
    {
        $this.data = null;
        $this.struck = "Demo";
    }
    
    public function getStruck(): string
    {
        return $this.stduck;
    }
    
    public function getData(): string
    {
        return $this.data;
    }
    
    public function setData(string $data): void
    {
        $this.data = $data;
    }
}

[推荐] 接口/方法/构造体缩进时建议花括号换行

对于接口/方法/构造体进行缩进时建议花括号换行,可以更好表示方法返回结果集包含内容.其余包含花括号的写法中花括号与主要结构中空格即可,不必要换行写

// 推荐写法
class feature {
    public function getData(string $data): string
	{
    	if ($this.data == $data) {
            return $this.data;
        }
	}
}

// 不推荐写法
class feature
{
    public function getData(string $data): string {
    	if ($this.data == $data)
        {
            return $this.data;
        }
	}
}

[强制] Json接口返回值编写

在定义对应的错误返回值内容,请开发者务必编写API接口文档,编写API接口文档请务必写明其对应结果产生时,会返回什么结果集.

不仅仅单独标注 output 输出结果或 status 状态结果,而是整个 Json接口 返回结果集.

需要具体写明数据返回的数据结构,不可单独列出结构或数据类型,必须两者均包含.

对于任何输出结果除本身以 string 数据类型数据,其余数据请填写对应数据类型,不可直接均已 string 数据类型定义