前端规范指南

本文最后更新于：6 个月前

HTML规范、CSS规范、JavaScript规范、Vue规范

前端规范指南（持续更新…）

编码未动，规范先行。好的规范对于开发，尤其是越大型的开发工作，具有举足轻重的影响。俗话说：代码不规范，同事两行泪。不仅仅是同事，即使是自己写的代码，如果不规范，没有语义化，自己过后阅读起来也是相当困难，阅读已经如此艰辛，更别说修改维护了。所以在开发过程中，严格遵守一套良好的规范，十分重要！

下文所有规范，博取各家所长，是笔者觉得大厂规范中哪些更规定更合理、更适用于自身所截取的，每条规范后面都注明了来源。

规范需要长期践行，因为短期记不住，需要靠不断地查来记住（背是不可能背的）

一、大厂规范清单

1. 凹凸实验室（京东）

链接：概述 | Aotu.io - 前端代码规范。基于 W3C、苹果开发者 等官方文档，并结合团队日常业务需求以及团队在日常开发过程中总结提炼出的经验而制定。

二、HTML规范

三、CSS规范

1. 选择器

  • 尽量少用通用选择器 *
  • 非必要不使用 ID 选择器
  • 不使用无具体语义定义的标签选择器

（参考：Aotu.io）

1
2
3
4
5
6
7
8
9
/* 推荐 */
.jdc {}
.jdc li {}
.jdc li p{}

/* 不推荐 */
*{}
#jdc {}
.jdc div{}

2. class命名

CSS中class的命名应尽量具体而简介（放大到选择器的命名也是如此），如果class名太过简单笼统，一是很容易命中非预期的目标，二是很容易被他处定义的样式覆盖。

  • 字母开头

  • 全部字母为小写

  • 单词之间统一用_连接

  • 命名原则：继承 + 外来

    1
    2
    3
    4
    <div class="modulename">
    	<div class="modulename_cover"></div>
    	<div class="modulename_info"></div>
    </div>

  • 当嵌套层数超过4级时，可以使用祖先模块内具有识辨性的独立缩写作为新的子孙模块

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <div class="modulename">
    	<div class="modulename_info">
        	<div class="modulename_info_user">
        		<div class="modulename_info_user_img">
        			<img src="" alt="">
        			<!-- 这个时候 miui 为 modulename_info_user_img 首字母缩写-->
        			<div class="miui_tit"></div>
        			<div class="miui_txt"></div>
        			...
        		</div>
        	</div>
        	<div class="modulename_info_list"></div>
    	</div>
    </div>

（参考：Aotu.io）

常见的class命名，更多请浏览：ClassName命名 | Aotu.io - 前端代码规范

ClassName 含义
bar 栏（工具类）
branding 品牌化
btn 按钮
caption 标题，说明（别只会用title了）
entry 文章，博文
meta 作者、更新时间等信息栏，一般位于标题之下
more 更多（展开）
fewer 收起
preview 预览
thumbnail 缩略图
wrapper 容器，包，一般用于最外层

3. 代码大小写

样式选择器，属性名，属性值关键字全部使用小写字母书写，属性字符串允许使用大小写。（参考：Aotu.io）

1
2
3
4
5
6
7
8
9
/* 推荐 */
.jdc{
	display:block;
}
	
/* 不推荐 */
.JDC{
	DISPLAY:BLOCK;
}

4. 代码格式：紧凑or展开

统一使用展开格式。（参考：Aotu.io）

1
2
3
4
5
6
7
8
/* 紧凑格式 */
.jdc{ display: block;width: 50px;}

/* 展开格式 */
.jdc{
    display: block;
    width: 50px;
}

5. 属性值引号

css属性值需要用到引号时，统一使用单引号。（参考：Aotu.io）

1
2
3
4
5
6
7
8
9
/* 推荐 */
.jdc { 
	font-family: 'Hiragino Sans GB';
}

/* 不推荐 */
.jdc { 
	font-family: "Hiragino Sans GB";
}

6. 属性书写顺序

建议遵循以下顺序：（参考：Aotu.io）

  1. 布局定位属性：display / position / float / clear / visibility / overflow
  2. 自身属性：width / height / margin / padding / border / background
  3. 文本属性：color / font / text-decoration / text-align / vertical-align / white- space / break-word
  4. 其他属性（CSS3）：content / cursor / border-radius / box-shadow / text-shadow / background / linear-gradient …

7. 注释规范

  • 单行注释 （参考：Aotu.io）

    1
    2
    /* 单行注释前后加空格 */
    .jdc {}

  • 多行注释 （参考：Aotu.io）

    1
    2
    3
    4
    5
    /**
     * @desc File Info
     * @author Author Name
     * @date 2015-10-10
     */

  • 模块注释 （参考：Aotu.io）

    1
    2
    3
    4
    5
    6
    7
    /* 模块注释
    ------------------------------------------ */
    .mod_a {}


    /* 模块注释之间相隔2行
    ------------------------------------------ */

四、JavaScript规范

1. 使用函数表达式

使用命名函数表达式而不是函数声明（参考：Airbnb）
为什么？函数声明会发生提升，这意味着在一个文件里函数很容易在其被定义之前就被引用了。这样伤害了代码可读性和可维护性。如果你发现一个函数又大又复杂，且这个函数妨碍了这个文件其他部分的理解性，你应当单独把这个函数提取成一个单独的模块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// bad
function foo() {
  // ...
}

// bad
const foo = function () {
  // ...
};

// good
// lexical name distinguished from the variable-referenced invocation(s)
// 函数表达式名和声明的函数名是不一样的
const short = function longUniqueMoreDescriptiveLexicalFoo() {
  // ...
};

(ps：使用命名函数表达式（第二种），比较容易；（第三种）就比较麻烦了，折中一下）

2. 变量命名

当命名变量时，主流分为「驼峰式命名」和「下划线命名」两大阵营。

在同一个项目中，指定其中一种，并在整个项目中严格遵守即可！ （参考：Aotu.io）

个人推荐使用 「下划线命名」，可读性更强！！尤其是变量名组成较复杂时。

3. 变量声明

  • JavaScript 允许在一个声明中，声明多个变量。但是建议一个声明只能有一个变量 （参考：Aotu.io）

    1
    2
    3
    4
    5
    6
    7
    // 不推荐
    const a, b, c

    //推荐
    const a
    const b
    const c

  • 尽量使用const （参考：Airbnb）

    为什么？因为这个能确保你不会改变你的初始值，重复引用会导致 bug 并且使代码变得难以理解

    1
    2
    3
    4
    5
    // 推荐
    const a = 1

    // 不推荐
    var a = 1

  • 要重新赋值的参数使用let （参考：Airbnb）

    为什么？因为 let 是块级作用域，而 var 是函数级作用域

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    // bad
    var count = 1;
    if (true) {
      count += 1;
    }

    // good, use the let.
    let count = 1;
    if (true) {
      count += 1;
    }

五、Vue规范

单文件组件中，script和css代码何时应该拆分成单独的文件，使用src属性引入？

当script或css代码量比较大的时候，比如超过了100行的时候，就可以将它们单独拆分出去了。这样做的目的是便于书写，因为拆分出去之后，可以更快地寻找到指定部分；如果不拆分出去的话，组件内部代码行数很多，增加了寻找指定代码的时间。

不过script部分一般不便于拆分出去，因为template中可能涉及需要在script中导入的组件或其它东西，如果将script拆分出去，书写代码的时候会出现报错

1. 目录命名

一个Vue项目，会建立很多文件目录，这些目录应该按照什么逻辑划分？目录的命名格式应该怎么样？

2. 文件命名

一个Vue项目，会涉及到很多类型的文件，.vue、.js、.css等，这些文件分别该按照什么样的格式命名？

  • .vue文件，

  • .css文件，全小写+下划线连接

    1
    jdc_list.css

六、commit规范

以下仅作为message的参考：

  • feat 增加新的功能
  • fix 修复 BUG
  • perf 优化功能
  • style 代码风格调整不影响运行结果的
  • refactor 重构代码
  • revert 撤销修改
  • test 测试相关
  • docs 文档和注释相关
  • chore 依赖更新/脚手架配置修改等
  • workflow 工作流改进
  • ci 持续集成
  • types 类型定义文件更改
  • wip 开发中
效率 > 规范化
#程序员的自我修养
前端规范指南
http://timegogo.top/2023/03/31/效率/规范化：前端规范指南/
作者
丘智聪
发布于
2023年3月31日
更新于
2023年9月9日
许可协议