phpDevelopDoc/CodeStyle.md

# 代码风格规约

## 命名风格

### <font color='red'>[强制]</font> 变量命名需要以驼峰方式

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

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

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

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

### <font color='red'>[强制]</font> 方法命名以驼峰方式

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

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

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

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

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

### <font color='red'>[强制]</font> 常量,枚举命名必须全部字符为大写

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

<font color='deepskyblue'>[推荐]</font> 对于常量,无特殊要求须设置为静态常量,方便调用及处理.

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

```php
// 允许的命名风格
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";
```

### <font color='red'>[强制]</font> 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`: 写明具体需要返回的内容,即参数

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



## 代码风格

### <font color='red'>[强制]</font> 构建形参必须标明类型

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

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

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

### <font color='deepskyblue'>[推荐]</font> 对于常量,无特殊要求须设置为静态常量

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

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

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

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

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

```php
// 不推荐写法
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;
    }
    */
}
```

### <font color='gold'>[参考]</font> 注意成员变量构建可见范围

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

```php
// 推荐写法
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;
    }
}
```

### <font color='deepskyblue'>[推荐]</font> 接口/方法/构造体缩进时建议花括号换行

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

```php
// 推荐写法
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;
        }
	}
}
```

### <font color='red'>[强制]</font> Json接口返回值编写

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

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

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

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