diff --git a/CodeStyle.md b/CodeStyle.md new file mode 100644 index 0000000..af90850 --- /dev/null +++ b/CodeStyle.md @@ -0,0 +1,222 @@ +# 代码风格规约 + +## 命名风格 + +### [强制] 变量命名需要以驼峰方式 + +为了保证变量命名可清晰辨认,在定义变量时,需要以驼峰方式进行命名. + +> 驼峰命名规范为,单个单词均使用小写字母,多个单词之间首单词首字母使用小写字母,后续单词中首字母使用大写字母. + +在变量命名中,请 [推荐] 给变量进行归类命名,例如 (数据库获取用户结果)`$resultUser`/(数据库获取书籍结果)`$resultBook`,(数组存储书本)`$arrayBook`/(数组存储Cookie)`$arrayCookie`. + +- 允许的命名 + - `$resultData`,`$arrayJson`,`$getDataForAdmin`等 +- 非法的命名 + - `$ResultData`,`$RESULTDATA`,`$resultdata`等 + +### [强制] 方法命名以驼峰方式 + +为了保证方法命名可清晰辨认,在定义方法时,需要以驼峰方式进行命名. + +> 驼峰命名规范为,单个单词均使用小写字母,多个单词之间首单词首字母使用小写字母,后续单词中首字母使用大写字母. + +在方法命名中,需要根据成员变量合理构建所需的方法,进行方法封装,设计成员变量的读取与成员变量的写入,例如: 定义用户年龄的成员变量 `$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() {} +``` + +### [强制] 常量,枚举命名必须全部字符为大写 + +对于(静态)常量或枚举常量,需要保证变量的命名为全大写,以特别明确分清楚大写内容为常量或枚举. + +[推荐] 对于常量,无特殊要求须设置为静态常量,方便调用及处理. + +```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"; +``` + +### [强制] 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 + } +} +``` + + + +## 代码风格 + +### [强制] 构建形参必须标明类型 + +避免方法中错误传参导致执行错误信息,在方法构建时,若设计形参构建,务必标明类型 + +```php +// 允许风格 +function setName(string $getName): void +{ + $this.name = $getName; +} + +// 非法风格 +function setName($getName): void +{ + $this.name = $getName; +} +``` + +### [推荐] 对于常量,无特殊要求须设置为静态常量 + +对于常量,无特殊要求须设置为静态常量,方便调用及处理. + +```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; + } + */ +} +``` + +### [参考] 注意成员变量构建可见范围 + +在一般开发中,若无特征说明该成员变量的用途,不推荐将其设置为 `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; + } +} +``` + +### [推荐] 接口/方法/构造体缩进时建议花括号换行 + +对于接口/方法/构造体进行缩进时建议花括号换行,可以更好表示方法返回结果集包含内容.其余包含花括号的写法中花括号与主要结构中空格即可,不必要换行写 + +```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; + } + } +} +``` + +### [强制] Json接口返回值编写 + +在定义对应的错误返回值内容,请开发者务必编写API接口文档,编写API接口文档请务必写明其对应结果产生时,会返回什么结果集. + +不仅仅单独标注 `output` 输出结果或 `status` 状态结果,而是整个 **Json接口** 返回结果集. + +需要具体写明数据返回的数据结构,不可单独列出结构或数据类型,必须两者均包含. + +对于任何输出结果除本身以 `string` 数据类型数据,其余数据请填写对应数据类型,不可直接均已 `string` 数据类型定义 + + + diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..638a50a --- /dev/null +++ b/Home.md @@ -0,0 +1,16 @@ +# 大学生电子书库开发规约 + +> 大学生电子书库(`ElectronicLibraryForCollegeStudents`)是一个为学生、教师和家长提供全面教材资源的在线平台。它整合了各种学科、年级和版本的电子教材,为用户提供方便快捷的教材搜索、筛选和获取功能的平台 + +本大学生电子书库开发规约适用于前后端开发者,在本开发规约中分为 `[强制]` , `[推荐]` , `[参考]` 部分,对于强制部分,开发者必须遵从开发规约,否则不允许进行项目推送及操作. + + + +## 规约目录 + +#### 1. [代码风格规约](./CodeStyle.md) + +#### 2. 事务操作规约 + +#### 3. 代码提交规约 + diff --git a/_Footer.md b/_Footer.md new file mode 100644 index 0000000..e69de29 diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..e69de29