Web 开发规则,代码规范
目录
警告
本文最后更新于 2023-07-07,文中内容可能已过时。
精神
- 绝不写死代码,硬编码
- 不留不要用的、垃圾代码
Git
- Master 的 BUG 必须最少且趋近于零,为最稳定的版本
- 每次 Commit 信息应该准确填写。不可模棱两可,eg: 修复 BUG、增加功能
- 禁止 Commit IDE 的 project data,e.g: .vscode
- 禁止上传垃圾代码
更多规则详见文档 Commit 规范
分支(Branch)
- 命名规则:应以此分支主要目的命名(修复什么 BUG,新增特定功能)
- 合并后的分支应该删除
commit
- 遵循一个功能一个 commit 的原则
Restful
资源名词站在 API 的角度思考
复数名词:可以复数笔数据,回传结果为 Array
举例:GET/users 取得多笔使用者资料
- 刪除,放在复数名词內,让 Router 保持一致性
- 增加,放在复数名詞內,让 Router 保持一致性
单数名词:仅取得单笔数据,必须指定 PK,两两一组,回传结果为 Object 举例:GET/user/{accont} 取得单笔使用者资料,必须指定 PK
URL 中一律不带 id 参数
|
|
更多规则详见文档 RESTful
命名
- 命名应根据内容做有意义的命名,让后续维护人员可以顾名思义!
- 即使不会发生错误,代码英文大小写也需明确区分。
语意
类型 | 命名规则 | 说明 |
---|---|---|
属性 (Attribute, Property) | 名词 user_name、userName | |
方法 (Method, Function) | 动词 + 名词 getUserName、get_user_name | 常見的动词有:get、set、update、delete、remove |
字母与分隔
语言 | 变量 (Variable, Parameter, Argument) | 常量 (Constant) | 面向对象 - 类名 (Class Name) | 面向对象 - 成员 (mebmer) |
---|---|---|---|---|
HTML | 全部小写,不同单词以「-」分隔 e.g: user-id | |||
CSS、SCSS | 全部小写,不同单词以「-」分隔,CSS 变量以「–」开头,SCSS 变量以「$」开头 e.g: .user-id、–header-height、$header-height | |||
JavaScript | 驼峰式命名法 首字小写,不同单字「首字以大写」分隔 e.g: userId | 全部大写,不同单字以「_」分隔 MAX_COUNT | 驼峰式命名法 首字大写,不同单字「首字以大写」分隔 一个文件放一个 Class, 文件名即为 Class Name e.g: User | 驼峰式命名法 公有 (public) : 首字小写,不同单词「首字以大写」分隔 e.g: name, getName 私有 (private): _公有命名规则 e.g: _name,_getName |
Vue | ||||
Java | ||||
PHP | 全部小写,不同单词以「_」分隔 e.g: user_id | |||
Python | ||||
SQL | 由使用者定义的:表名、字段名 全部小写,不同单词以「_」分隔 | SQL 语法、函数全部大写 e.g: SELECT、INSERT INTO |
通用
- 代码编写
- 每个函数应该使用块注释,注释应包含函数功能说明、参数说明。规则见:JSDoc、JavaDoc
- 不必要的代码不要写,也应禁止放到注释里面!
- if-else 的 {} 严禁省略
- 代码规范、代码排版等可通过 eslint 等工具做统一处理
正确写法
|
|
错误写法
|
|
- 代码排版
- 任何代码应该以 2 个 space 为一个缩进做好排版、不可使用 tab
- 函数 (Function, Methd)
- 函数声明时需在函数上方加上函数注释,注释应包含函数说明、参数内容(参数类型、参数英文名称、参数说明)、返回值内容(返回值类型、返回值说明)
- 类 (Class)
- 一个类(Class)的声明只能存在一个文件
- 类(Class)的声明文件,文件名必须为类名
- 其他
- 连接本地任何其他资源(图片、文件、网站)皆使用相对路径,禁止使用绝对路径,非本地资源除外
HTML
代码编写
- 禁止在 HTML 使用
<style>
、<script>
,一律使用外部档案引用方式引用 CSS、JavaScript 文件 - HTML 标签需成双成对,有头有尾
- 块级标签:
<tag></tag>
- 单标签:
<tag />
- 禁止使用已被 HTML 舍弃的旧标签、属性,如:
|
|
CSS
CSS 的定义应该独立一个 CSS 文件,禁止使用
<style>
或style
属性直接在 HTML 中定义样式。
JavaScript
禁止使用 HTML 字串,一律使用 Dom 产生 HTML, e.g:
document.createDocumentFragment()
注释
JavaScript 注释应该遵循 JSDoc 的标准撰写
全局变量 (Global)
|
|
常量 (Constant)
|
|
Example
|
|
函數、方法 (Function, Method)
|
|
Example
|
|
Vue
- 待补充
Java
Java 注释应该遵循 JavaDoc 的标准撰写
- 待补充
PHP
前端参数取得
参数取得需通过 filter_input 函数取得,不得使用 _GET 、_POST
输出到前台
参数命名必须为:全部小写,不同单字以「_」分隔
注解
PHP 注解应该遵循 PHPDoc 的标准撰写
成员变量 (Member)
成员变量只的是 Class 内的成员变数,我们都会要求替成员变量增加注解说明。通常 Function 的变量除非太特别否则都不需要特别注解说明。
|
|
Example
|
|
函数、方法 (Function, Method)
|
|
Example
|
|
Python
- 待补充
Database
- 禁止使用 Table Join。
- 禁止使用 Oracle Trigger。
- 禁止将查询数据库的 SQL 放在循环中查询
SQL 撰写
- 属于 SQL 语法使用大写(SELECT,WHERE,INSERT etc..)
- 属于使用者自己定义的使用小写(表名 table name,字段名 column name etc..)
- 表名、字段名前后需加上 `
Example
|
|
统一用词
系统中常用词,例如弹出框按钮、搜索框等,仅为举例,不限与此。
用词 | 统一 |
---|---|
最后、最终 | 最后 |
关闭、Cancel、取消 | 取消 |
存储、保存、修改、OK、确定 | 确定 |
搜寻、查询、查找、搜索 | 搜索 |
Buy me a coffee~
支付宝
微信