前端开发规范

# 代码风格

如果代码编辑器用的是 vscode，安装 Vetur、Eslint、Prettier 等插件，在开发过程中就可以利用编辑器对代码格式化和 Eslint 校验

当代码中出现(红色波浪线 || 黄色波浪线)的时候，就表明此位置是不符合规范的，鼠标移上查看不规范的说明，更多的到Eslint 官网 (opens new window)查询如何写才符合规范，有些规范是在 Eslint 官网查不到的，有可能是别人写的 Eslint 插件，这时就需要到 Github 查找对应的插件说明了

eslint-error

# 编码规范

scss : className 的单词之间以“-”连接,如z-panel-body; 相同的样式值多次使用到请使用变量（scss 变量写法如：$--border-color:#f0fef2）;

$--header-color: #666666;
.z-header-text {
    color: $--header-color;
}
.z-body {
    background-color: lighten($--header-color, 70%);
}

1
2
3
4
5
6
7

scss : 样式类名的嵌套权重如果不是非必要的，嵌套控制在三层之内，尽量减少嵌套写法;

// 不提倡
.z-panel {
    position: relative;
    .header {
        height: 40px;
        .text {
            font-size: 18px;
            &:hover {
                color: #666666;
            }
            img {
                width: 20px;
            }
        }
    }
}
// 提倡
.z-panel {
    position: relative;
}
.z-panel-header {
    height: 40px;
}
.z-panel-header-text {
    font-size: 18px;
    &:hover {
        color: #666666;
    }
    & > img {
        width: 20px;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

js : 变量名和普通函数名如果是多个单词,请使用骆驼峰形式如myName，构造函数名和 class 类名,请以首字母大写、多个单词以骆驼峰形式，如MyComponent;
js : 声明函数参数超过 3 个时，请使用对象参数形式，如 showMyDreams(show,isBox,byElement)==>showMyDreams({show,isBox,byElement,allData});
.js 、 .jsx 文件的代码行数，以及.vue内的 template + script 的代码行数，尽量控制在不超过 400行，能拆分文件就拆分文件
.vue 文件的 template 自定义组件的引用，以MyComponent、my-component形式使用

<template>
    <el-row>
        <el-col><UploadForm /></el-col>
    </el-row>
</template>
<script>
    import UploadForm from './uploadForm.vue';
    import { Row, Col } from 'element-ui';
    export default {
        components: { UploadForm, ElRow: Row, ElCol: Col },
    };
</script>

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

不规范：

<template>
    <uploadForm />
</template>
<script>
    import uploadForm from './uploadForm.vue';
    export default {
        components: { uploadForm },
    };
</script>

1
2
3
4
5
6
7
8
9

良好的变量命名语义、良好的注释风格，提高代码的可读性，从而提高代码的可维护性

# 注释规范

好的注释包括：

帮助读者更好地了解代码逻辑和结构，例如：
这里更多说的是注释风格，并不是每一行都应该加注释，如下的有些变量命名是顾名思义的，已经充当了注释的效果

init: function() {
  // 获取配置信息
  const config = getConfig();

  // 获取用户信息
  const userInfo = getUserInfo();

  // 根据配置和用户信息，进行初始化
  doInit(config, userInfo);

  // 如果存在自定义配置时的特殊逻辑
  if (config.custom) {
    ...
  }
}

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

复制代码特殊或不易理解写法的解释说明，例如：

/**
 * parseInt was the reason my code was slow.
 * Bitshifting the String to coerce it to a
 * Number made it a lot faster.
 */
const val = inputValue >> 0;

1
2
3
4
5
6

特殊标记注释：如 TODO、FIXME 等有特殊含义的标记

class Calculator extends Abacus {
    constructor() {
        super();

        // FIXME: shouldn’t use a global here
        total = 0;

        // TODO: total should be configurable by an options param
        this.total = 0;
    }
}

1
2
3
4
5
6
7
8
9
10
11

文件注释：部分规约会约定在文件头部书写固定格式的注释，如注明作者、协议等信息
文档类注释：部分规约会约定 API、类、函数等使用文档类注释（如 jsdoc 风格）

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title = title;
    this.author = author;
}

Book.prototype = {
    /**
     * 获取书本的标题
     * @returns {string|*}
     */
    getTitle: function () {
        return this.title;
    },

    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum: function (pageNum) {
        this.pageNum = pageNum;
    },
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

遵循统一的风格规范，如一定的空格、空行，以保证注释自身的可读性

# Git 提交规范

commitlint + husky + lint-staged + +prettier + eslint

使用husky来管理 git-hooks，提交代码时会执行 git 钩子，自动格式化文件代码，执行 Eslint 检测，检测不通过是无法提交代码的

提交时要写提交说明，使用 commitlint来校验提交说明的规范

提交格式（注意冒号后面有空格）

git commit -m <type>[optional scope]: <description>

type: 用于表明我们这次提交的改动类型，是新增了功能？还是修改了测试代码？又或者是更新了文档？
optional scope: 一个可选的修改范围。用于标识此次提交主要涉及到代码中哪个模块。
description: 描述此次提交的主要内容。

示例

git commit -m 'fix(scope): 修复xxx的bug'
git commit -m 'refactor(): 重构整个项目'
git commit -m 'feat(): 新增了xxx的功能'

1
2
3

提交的每一条内容需要表明是否依赖后端

定一个规范：

【UI】："只有前端，不依赖后端" 【BOTH】："前后端一起才能正常运行"

示例

# 多行内容
git commit -m "chore(scope): 2022-09-08
【UI】修复了...
【BOTH】新增了...
【BOTH】修改了...
"

1
2
3
4
5
6

常用的 type 类型

type	语义
build	编译相关的修改，例如发布版本、对项目构建或者依赖的改动
chore	其他修改, 比如改变构建流程、或者增加依赖库、工具等
ci	持续集成修改
docs	文档修改
feat	新特性、新功能
fix	修改 bug
perf	优化相关，比如提升性能、体验
refactor	代码重构
revert	回滚到上一个版本
style	代码格式修改, 注意不是 css 修改
test	测试用例修改