Web 开发规则，代码规范

1 精神

• 绝不写死代码，硬编码
• 不留不要用的、垃圾代码

2 Git

• Master 的 BUG 必须最少且趋近于零，为最稳定的版本
• 每次 Commit 信息应该准确填写。不可模棱两可，eg: 修复 BUG、增加功能
• 禁止 Commit IDE 的 project data，e.g: .vscode
• 禁止上传垃圾代码

更多规则详见文档 Commit 规范

2.1 分支（Branch）

• 命名规则：应以此分支主要目的命名（修复什么 BUG，新增特定功能）
• 合并后的分支应该删除

2.2 commit

• 遵循一个功能一个 commit 的原则

3 Restful

• 资源名词站在 API 的角度思考

  • 复数名词：可以复数笔数据，回传结果为 Array

    举例：GET/users 取得多笔使用者资料

    • 刪除，放在复数名词內，让 Router 保持一致性
    • 增加，放在复数名詞內，让 Router 保持一致性

  • 单数名词：仅取得单笔数据，必须指定 PK，两两一组，回传结果为 Object 举例：GET/user/{accont} 取得单笔使用者资料，必须指定 PK

• URL 中一律不带 id 参数

1
2

正确范例： calendar_manager/calendar/29
错误范例： calendar_manager/calendar/29?id=29

更多规则详见文档 RESTful

4 命名

• 命名应根据内容做有意义的命名，让后续维护人员可以顾名思义！
• 即使不会发生错误，代码英文大小写也需明确区分。

4.1 语意

4.2 字母与分隔

5 通用

• 代码编写
• 每个函数应该使用块注释，注释应包含函数功能说明、参数说明。规则见：JSDoc、JavaDoc
• 不必要的代码不要写，也应禁止放到注释里面！
• if-else 的 {} 严禁省略
• 代码规范、代码排版等可通过 eslint 等工具做统一处理

5.1 正确写法

1
2
3
4
5
6

public function test () {
  // do something
  if (a === b) {
    // do something
  }
}

6 错误写法

1
2
3
4
5
6
7
8

public function test ()
{
  // do something
  if (a === b)
  {
    // do something
  }
}

• 代码排版
  • 任何代码应该以 2 个 space 为一个缩进做好排版、不可使用 tab
• 函数 (Function, Methd)
  • 函数声明时需在函数上方加上函数注释，注释应包含函数说明、参数内容（参数类型、参数英文名称、参数说明）、返回值内容（返回值类型、返回值说明）
• 类 (Class)
  • 一个类（Class）的声明只能存在一个文件
  • 类（Class）的声明文件，文件名必须为类名
• 其他
  • 连接本地任何其他资源（图片、文件、网站）皆使用相对路径，禁止使用绝对路径，非本地资源除外

7 HTML

7.1 代码编写

• 禁止在 HTML 使用 <style>、<script>，一律使用外部档案引用方式引用 CSS、JavaScript 文件
• HTML 标签需成双成对，有头有尾
• 块级标签：<tag></tag>
• 单标签：<tag />
• 禁止使用已被 HTML 舍弃的旧标签、属性，如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<!-- html tag -->
<center>
<font>
<basefont>
<s>
<strike>
<u>
<listing>
<plaintext>
<xmp>
<!-- html attribute -->
align
bgcolor
color

8 CSS

CSS 的定义应该独立一个 CSS 文件，禁止使用 <style> 或 style 属性直接在 HTML 中定义样式。

9 JavaScript

禁止使用 HTML 字串，一律使用 Dom 产生 HTML, e.g: document.createDocumentFragment()

9.1 注释

JavaScript 注释应该遵循 JSDoc 的标准撰写

9.1.1 全局变量 (Global)

1

/* global ZT */

9.1.2 常量 (Constant)

1
2
3
4

/**
 * 常量說明
 * @type {常量类型}
 */

Example

1
2
3
4
5

/**
 * 请求地址
 * @type {String}
 */
const REQUEST_URL = 'http://localhost:8080';

9.1.3 函數、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param {参数类型} 参数名称参数说明
 * @param {参数类型} [选择性参数名称] 参数说明
 * @param {参数类型} [选择性参数名称=参数预设值] 参数说明
 * @returns {返回值类型} 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/**
 * 取得使用者
 * @param {Int} userId 使用者 ID
 * @param {Object} [options] 其他选项
 * @param {String} [options.query='a'] 查询关键词 默认为 'a'
 * @returns {Object} 使用者资料
 */
function getUser(userId, options) {
  // do something
  return user;
}

10 Vue

• 待补充

11 Java

Java 注释应该遵循 JavaDoc 的标准撰写

• 待补充

12 PHP

12.1 前端参数取得

参数取得需通过 filter_input 函数取得，不得使用 _GET、_POST

12.2 输出到前台

参数命名必须为：全部小写，不同单字以「_」分隔

12.3 注解

PHP 注解应该遵循 PHPDoc 的标准撰写

12.4 成员变量 (Member)

成员变量只的是 Class 内的成员变数，我们都会要求替成员变量增加注解说明。通常 Function 的变量除非太特别否则都不需要特别注解说明。

1
2
3
4

/**
 * 成员变量說明
 * @type {类型}
 */

Example

1
2
3
4
5

/**
 * 使用者 ID
 * @type {String}
 */
$userId = 'Hello';

12.5 函数、方法 (Function, Method)

1
2
3
4
5
6
7

/**
 * 函数用途说明
 * @param 参数型态 参数名称 参数说明
 * @option 参数选项类型 参数选项名称 参数选项说明
 * @uses 全局变量 全域变数说明
 * @returns 返回值类型 返回值说明
 */

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

/**
 * 取得使用者
 * @param int userId 使用者 ID
 * @param object options 其他选项
 * @option string options['query'] 查询关键字
 * @uses $_POST['role_id'] 从前端以 POST 取得角色 ID
 * @returns object 使用者资料
 */
function getUser ($userId, $options) {
  // do something
  return $user;
};

13 Python

• 待补充

14 Database

• 禁止使用 Table Join。
• 禁止使用 Oracle Trigger。
• 禁止将查询数据库的 SQL 放在循环中查询

14.1 SQL 撰写

• 属于 SQL 语法使用大写（SELECT，WHERE，INSERT etc..）
• 属于使用者自己定义的使用小写（表名 table name，字段名 column name etc..）
• 表名、字段名前后需加上 `

Example

1

INSERT INTO `user` VALUES('a', 'b');

15 统一用词

系统中常用词，例如弹出框按钮、搜索框等，仅为举例，不限与此。