一些开发规则

2023-12-11 20:26:53 浏览数 (1)

精神

  • 代码优雅，可读性高。
  • 注释内容简明扼要。
  • 绝对不能写死程序。
  • 不留不要用的、垃圾程序代码。
  • 其他内容看详情。

Git

  • Master 的 版本必须是最稳定的版本。
  • 每次 Commit 信息应该如实填写，不可模棱两可。
  • 禁止 上传 IDE 的 project data。
  • 开始工作前应先进行fetch/pull同步远程代码，并解决冲突，然后再开始写代码。

分支 (Branch)

  • Master 仅为已是出的版本内容，BUG 必须最少且趋近于零，为最稳定的版本。
  • 命名规则：应以此分支主要目的命名 (修复BUG、新增某特定功能)。
  • rc 为候选释出的版本内容，尚未释出的修改内容都必须合并回 rc 。
  • 不可出现版本号、文件名、档目录信息。
  • 合并后的分支应删除。

Commit

基本原则

  • 一个功能commit一次，应同时修改更新日志。
  • commit前应确认所提交文件及修改确实无误
  • 禁止 commit 测试代码 (如：var_dump, dd, console.log, alert 等)

基本样板

commit message 须遵循以下规范：

(若有 issue / pull request 一律需附上编号) {type}:{subject (并在50个字内)} #{issue/pull request}

详细规则

type

类型

范例

说明

调整

Feat

Feat: {变动或新增/优化内容} (#issueID)

调整功能，需叙述现况(before)、调整后(after)。

新增

Add

Add: {单纯新增内容} (#issueID)

单纯新增功能

删除

Remove

Remove: {删除内容} (#issueID)

删除功能，须说明删除原因。

修正

Fix

Fix: {修复内容} (#issueID)

修复已知的 BUG

重写

Refactor

Refactor: {重写功能名称} (#issueID)

不是新增功能，也不是修补 bug 的程序代码变动，单纯重写某个功能的程序代码，并不影响功能结果。

优化

Perf

Perf: {改善内容} (#issueID)

改善程序代码的效能

退版

Revert

Revert: {恢复的版本 commit message 原因} (#issueID)

恢复某一个 commit 的版本

格式

Style

Style: {修改内容} (#issueID)

不影响代码含义的更改(例如空格、格式化、少了分号等等)

文档

Docs

Docs: {调整内容} (#issueID)

只是文档的更改

工具

Chore

Chore: {工具内容/功能} (#issueID)

对构建或者辅助工具的更改

测试

Test

Test: {测试功能/代码的调整} (#issueID)

添加或修正测试

Tags

命名原则

  • 小变动升小版号 1.0.0=>1.0.1
  • 资料表变动或者较大调整升中版号 1.0.0=>1.1.0
  • 重大变动或架构调整升大版号 1.0.0=>2.0.0

删除原则

  • 版号过多时可删除非重要版号
  • 应至少保留每个中版号的最新一版
  • 应至少保留最近更新的十个版号

Restful

  • URL中不应该包含动词。
  • URL的结尾不应该包含 ‘/’（有‘/’和无‘/’表示的资源是不同的）。
  • URL中的正斜杠 ‘/’必须用于表达层次关系。
  • URL中应该使用‘-’连接单词提高可读性，而不是‘_’。
  • URL路径中首选小写字母。
  • URL路径中的名称应使用复数形式（除非资源为唯一资源）。

命名

  • 命名应根据内容做有意义的命名，让后续维护人员可以一目了然!
  • 即使不会发生错误，程序代码英文大小写也需明确区分。
  • 我自己的标准是：
    1. 绝对不可使用没有意义的命名。
    2. 变量和函数命名最好是（动词 名词：setName、getId或者set_name、get_id等等）。
    3. 资源命名最好是（使用下划线区分：nav_logo.png等等)。
    4. css id、class命名最好是（名词短语，以 - 隔开：user-id等等）。

语意

类型

命名规则

说明

属性 (Attribute, Property)

名词user_name、userName

方法 (Method, Function)

动词 名词getUserName、get_user_name

常见的动词有：get、set、update、delete、remove

不管使用以上哪种规则，在开发同一个项目时，必须使用同一种规则，严禁混用。

注意：我自己是这样使用的：在JavaScript中，属性、变量和方法命名都使用字母大小写区分的方式；在php中，变量和方法命名使用下划线区分的方式。但是，在面向对象编程中，class中，全部使用字母大小写区分，类名的所有单词首字母大写，并且文件名即类名。

附加表

类型

面向对象中动词使用

数据库

METHOD(restful)

增-CREATE

add/create

INSERT

GET

查-READ

get/list

SELECT

POST

改-UPDATE

set/replace/edit/add

UPDATE

PUT/PATCH

删-DELETE

remove/delete

DELETE

DELETE

字母与分隔

语言

变量 (Variable, Parameter, Argument)

常量 (Constant)

面向对象 - 类名 (Class Name)

面向对象 - 成员 (mebmer)

HTML、CSS

全部小写，不同单字以「-」分隔user-id

JavaScript

首字小写，不同单字「首字以大写」分隔userId

全部大写，不同单字以「_」分隔MAX_COUNT

首字大写，不同单字「首字以大写」分隔一个文件放一个 Class文件名即为 Class NameUser

公有 (public) : 首字小写，不同单字「首字以大写」分隔name, getName私有 (private): _公有命名规则_name, _getName

PHP

全部小写，不同单字以「_」分隔user_id

SQL

由使用者定义的：表名、字段名全部小写，不同单字以「_」分隔

SQL语法、函数全部大写SELECT、INSERT INTO

通用

  • 程序代码编写
  • 每个函数应该注释，注释应包含函数功能说明、自变量说明。
  • 不必要的代码不要写，也禁止放到注释里面!
  • if-else 的 {} 严禁省略。
  • {} 起始一律跟在前一个功能的最后，禁止换行

正确写法

代码语言：javascript复制
public function test(){
  //do something
  if($a === $b){
    //do something
  }
}

错误写法

代码语言：javascript复制
public function test()
{
  //do something
  if($a === $b)
  {
    //do something
  }
}
  • 程序代码排版
    • 任何程序代码应该以 2 个 space 为一个阶层做好排版、不可使用 tab。
  • 函数 (Function, Methd)
    • 函数声明时需在函数上方加上函数注释，注释应包含函数说明、自变量内容 (自变量类型、自变量英文名称、自变量说明)、 回传值内容 (回传值类型、回传值说明)
  • 类 (Class)
    • 一个类 (Class) 的声明只能存在一个文件。
    • 类 (Class) 的声明文件，文件名必须为类名。
  • 其他
    • 链接本地任何其他资源 (图片、文件、网站) 皆使用相对路径，禁止使用绝对路径，非本地资源除外。

HTML

程序代码编写

禁止在 HTML 使用 <style>、<script>，一律使用外部文件引用方式引用 CSS、JavaScript文件。

HTML 标签需成双成对，有头有尾。

区块标签：<tag></tag>

单标签：<tag />

禁止使用已被 HTML 舍弃的旧标签、属性，如：

代码语言：javascript复制
<!-- html tag -->
<center>
<font>
<basefont>
<s>
<strike>
<u>
<listing>
<plaintext>
<xmp>
<!-- html attribute -->
align
bgcolor
color

CSS

程序代码编写

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

就算是自己本身写测试代码，使用 "<style>" 或者 "<script>" 也应该明确写出 "[type]" 属性。

JavaScript

程序代码编写

禁止使用 HTML 字符串，一律使用 Dom 产生 HTML

禁止省略箭头函数 (Arrow function) 的括号 正确

代码语言：javascript复制
a = (a, b) => {
  c;
}

错误 (这是允许的，但造成程序代码阅读困难，故禁止)

代码语言：javascript复制
a  => c;

注释

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

全局变量 (Global)

代码语言：javascript复制
/* global $b, Biugle */

常量 (Constant)

代码语言：javascript复制
/**
 * 常量说明
 * @type {常量类型}
 */

Example

代码语言：javascript复制
/**
 * 使用者ID
 * @type {String}
 */
var userId = 'Hello';

函数、方法 (Function, Method)

代码语言：javascript复制
/**
 * 函数用途说明
 * @param {自变量类型} 自变量名称 自变量说明
 * @param {自变量类型} [选择性自变量名称] 自变量说明
 * @param {自变量类型} [选择性自变量名称=自变量默认值] 自变量说明
 * @returns {回传值类型} 回传值说明
 */

Example

代码语言：javascript复制
/**
 * 取得使用者
 * @param {Int} userId 使用者ID
 * @param {Object} [options] 其他选项
 * @param {String} [options.query='a'] 查询关键词 默认为 a
 * @returns {Object} 用户数据
 */
var getUser = function(userId, options){
  //do something
  return user;
};

另外补充一点，在调试Js代码后，通常要强制刷新后才有效。在Js中，通常使用一些方法或者css属性时，有 "-" 的应该改为后面第一个单词字母大写。（例：font-weight=>fontWeight）

PHP

前端参数取得

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

输出到前台

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

注释

PHP 注释应该遵循 PHPDoc 的标准编写

成员变量 (Member)

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

其他

目录一律使用小写字母，目录分隔符需考虑Linux与Windows的情况不同而改变。

代码语言：javascript复制
/**
 * 成员变量说明
 * @type {类型}
 */

Example

代码语言：javascript复制
/**
 * 使用者ID
 * @type {String}
 */
$userId = 'Hello';

函数、方法 (Function, Method)

代码语言：javascript复制
/**
 * 函数用途说明
 * @param 自变量类型 自变量名称 自变量说明
 * @option 自变量选项类型 自变量选项名称 自变量选项说明
 * @uses 全局变量 全局变量说明
 * @returns 回传值类型 回传值说明
 */

Example

代码语言：javascript复制
/**
 * 取得使用者
 * @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;
};

Database

  • 禁止使用 Table Join。
  • 禁止使用 Oracle Trigger。
  • 禁止将查询数据库的 SQL 放在循环中查询SQL 编写
  • 属于 SQL 语法使用大写 (SELECT, WHERE, INSERT etc..)
  • 属于使用者自己定义的使用小写 (表名 table name, 字段名 column name etc..)
  • 表名、字段名前后需加上 `

Example

代码语言：javascript复制
INSERT INTO `user` VALUES('a', 'b');

统一用词

仅为举例，不限于此。碰到问题，再行商榷。

用词

统一

最后

最后

关闭离开Cancel

取消

存储储存修改

保存

搜寻搜索Search

查询

OK确认Confirm

确定

移除RemoveDelete

删除

文档编写

  1. 中文时使用中文符号，注意标点使用，有逗号时必须使用结束标点符号。
  2. 英文时使用英文符号，要求同上。
  3. 注意换行与空白，不要留多余空白空格。
  4. 内容区块需使用空行隔开，不要出现奇怪的隔开符号或者换行符号。
  5. 使用 MarkDown 时请注意排版，表格请统一格式，不要为了对齐而对齐。
  6. 不要出现错别字与错误的标点符号
  7. 英文数字或字符需要与中文字符隔一个空格
  8. 一定要注意排版，排版必须整洁，突出重点。且内容无重复、多余的部分，也不能出现与文档无关的内容。
  9. 示例代码一定要经过验证，且同时要保证其遵循开发规范与代码标准，不要出现晦涩难懂的代码或者无意义的范例。
  10. 写完后必须预览检查，确保文字、排版、内容、范例、格式、标点均无误方可提交。
变量 测试 函数 开发 前端

0 人点赞