前端编码推荐规范及实践指引（一）

FE

为什么需要规范

好的代码应该是让人阅读起来赏心悦目的，但是在实际项目中（尤其是项目体量一旦变大）想做到这一点却十分困难，现实情况是每次 debug 或者代码重构都是一件让人十分头疼的事，原因很多：

1. 人员流动
2. 团队惰性
3. 缺乏代码审查（Code Review）
4. 没有利用代码约束的技术或工具
5. ……

尤其前端方向（HTML、CSS 和 JavaScript）语法是松散灵活的，没有约束指导后大部分团队在实际项目中的现状是：

1. 命名冲突
2. 代码语义化不强，不明所以
3. 大量无用的历史冗余代码，又不敢随意删除
4. 复用性（模块性）不强
5. ……

而我们可以对此采取哪些措施呢？

1. 制定编码规范
2. 严格执行编码规范
3. 团队代码审查
4. 宁可相信程序也不要相信人，利用 Lint 工具/IDE/插件 来提高代码质量

本文尝试总结一套前端编码规范，并将介绍相关的辅助工具以达到实践指引的目的。

HTML/CSS 规范

为最大限度解决协同合作过程中出现的命名冲突问题、方便理解代码上下文、提高代码的执行效率，同时缩短项目交接时间、有必要制定一套简单易用的命名规范。基本原则是 class 需要遵循其代表的功能语义，模块化开发，不同业务模块使用不同前缀，公共部门使用项目缩写为前缀。

—— QMUI Web

基本要求：

1. 命名简短、语义化、忌拼音、忌生僻缩写
2. 标签语义化（反面：一路 div 到底）
3. 基本符合 W3C Markup Validation 与 W3C CSS Validation 检测规则

推荐规范：

1. UI 库/框架前缀，公共组件前缀，业务逻辑前缀
2. 推荐 _ 做为 层级 连接符，- 承担功能前缀或后缀链接符

3. 单词如过长或不便拆分则允许多单词小驼峰的写法

   <div class="profile_cnt">
       <div class="profile_cnt_title"></div>
       <div class="profile_cnt_txtErrWrap"></div>
   </div>

4. 嵌套语义化 DOM 结构（父子关系）
5. 同级扩展关系以大写区分

6. id 或 js- 前缀类名供 JS 专用

   <div class="profile_cnt_btn js-profileCntBtn"></div>
   <div class="profile_cnt_btn" id="profileCntBtn"></div>

7. ……

1. 关于前缀

一般我们的项目的 UI 代码会由数个部分组成：

1. 公司/部门/团队级基础公共 UI 组件（可能没有，视情况而定）
2. 针对项目制定的 UI 组件
3. 具体的模块代码

最终前端 UI 的呈现就是上述三部分的拼合与复写。

现假设 Hope 公司的情况如下：

公司经过了许许多多项目的开发，总结了一套适用于所有（大部分）项目的 UI 组件，叫做 Hope UI，已封装好，可方便地供所有项目使用。

Hope 公司正在做一个项目，项目代号为 Chem，设计师已经绘制出了一套 UIKit。

代码实例：

<!-- hp 为团队公共 UI 组件前缀 -->
<!-- ce 为项目 UI 组件前缀 -->
<a class="hp_btn ce_btn profile_cnt_btn" href="javascript:;">按钮1</a>

2. 嵌套结构

先看一段代码实例：

<div class="profile_header">
    <div class="profile_header_title">
        <span class="profile_header_title_icon hp_icon ce_icon ce_icon_hand"></span>
        <h1 class="profile_header_title_txt">
        </h1>
    </div>
</div>
<div class="profile_cnt">
    ...
</div>

像上面一样书写什么好处呢？

1. DOM 结构非常清晰，看到类名便知晓其父级结构、子级结构
2. 再也不需要绞尽脑汁编类名了
3. 命名的冲突不会再出现

4. 如果使用了 Sass/Less 来编写预处理的 CSS 时就更加幸福了，如下：

   .profile {
       &_header {
           height: 150px;
           background-color: #666;
           &_title {
               display: inline-block
               &_txt {
                   font-size: 18px;
               }
           }
       }
       &_cnt {
           background-color: #ccc
       }
   }

5. ……

3. 同级特异扩展

先看如下代码：

<div class="profile_header">
    <div class="profile_header_title">
    </div>
    <!-- 注意这里的 `-Red` -->
    <div class="profile_header_title profile_header_title-Red">
    </div>
</div>
<div class="profile_cnt">
    ...
</div>

上面的 profile_header_title 与 profile_header_title-Red 是同一级的，所以二者都有 profile_header_title 部分，-Red 的首字母大写并使用-（而非_）连接，表示是前一级的特异扩展，而不是父子 DOM 的关系。

4. 当类名层级太长

类名一般做好不要超过 5-6 个层级，即 _ 分隔的部分不要多达 6 个以上。

当理论类名层级过长，例如：

...
    <div class="profile_cnt_nav_list_item_left_title">
    </div>
...

那么遵循以下原则：

1. 不允许缩写（看代码的人已经不知道你写的是什么了）：

   <!-- not good -->
   class="pcnlil_title"

2. 第层不能省
3. 省前不省后（省略位置考前的）
4. 其后代 DOM 需要与其省略一直

...
    <div class="profile_cnt_nav_list_item_left_title">
    </div>
    <!-- To -->
    <div class="profile_list_item_left_title">
    </div>
...

4. JS DOM 的特征化识别

1. 使用 js- 前缀 + 小驼峰 类名，例如：

   <div class="profile_header js-profileHeader">
   </div>

2. 或使用小驼峰 id（尽可能用类名来小驼峰化）

   <div class="profile_header" id="profileHeader">
   </div>

5. 注释规范

HTML 注释要注意注释内容与前后 - 之间的空格：

<!-- comments come to here -->

CSS 单行注释注意内容与前后 * 之间的空格：

/* comments come to here */

CSS 多行注释：

/**
 * comments come to here
 */

CSS 重要注释（不会被编译、压缩工具丢弃）

/*!
 * important comments come to here
 */

6. 其他细则

团队可参考以下资料自己整理制定：

1. Popular Coding Convention on Github
2. Code Guide - en
3. Code Guide - zh-cn

JavaScript 规范

1. 命名

一般变量与函数名统一采用驼峰，禁止出现 _ - 连接的形式：

// good
var totalNum = 10;
function getTotalNum() {
    // ...
}
// not good
var total-num = 10;
var total_num = 10;

常量采用全大写，单词间以 _ 分隔：

// good
const MAX_COUNT = 20; // ES6 写法
var MAX_COUNT = 20; // ES5 写法

jQuery 对象使用 $ 做为特征字符识别：

var $body = $('body');

2. 模块化

模块化现在已经成了业界的共识，大大提高了我们的开发效率，改善了我们的开发体验，提高了的代码的复用，降低了 Debug 的时间成本。

模块化需要花费比较大的篇幅讲解，并且需要根据团队的需求进行特异性定制，本文在此不赘述。

3. 其他细则

其他细则就不必说了，因为 ESLint 能帮助我们做剩下的代码规范检查工作。许多十分愚蠢与不经意的错误能够得到极大程度的避免，开发效率提升不止一点。

现在主流的开源前端项目基本上全部使用了 ESLint 做为其审查工具以保证代码的质量与持续开发，学习与配置使用 ESLint 是一劳永逸的事情，有助于团队成员持续 养成代码洁癖。

ESLint 推荐配置文件 .eslintrc.js：

module.exports = {
    extends: ['standard', 'eslint:recommended'],
    parserOptions: {
        ecmaVersion: 6,
        sourceType: 'module'
    },
    env: {
        es6: true,
        node: true,
        browser: true,
        mocha: true,
        amd: true,
        jquery: true
    },
    plugins: [
        'standard'
    ],
    global: {
        ENV: true
    },
    rules: {
        semi: [1, 'always'],
        indent: [2, 4, {
            SwitchCase: 1
        }],
        quotes: [2, 'single'],
        'linebreak-style': [2, 'unix'],
        'no-console': [1],
        'no-unused-vars': [1]
    }
};

下篇预告

本文或详细或粗糙地讲述了 HTML/CSS/JavaScript 的规范问题，没提到的部分网上都有相关文章或资料可查阅。

下篇文章将介绍各个代码审查工具（ESLint、CSSLint、Sublimelinter 相关插件等）的使用与配置。

下下篇文章将讲述前端的模块化开发，如何配置模块化、工程化、自动化的工程架构，以及如何将各个辅助工具集成到我们的工程架构里。

舒适的开发环境来源于规范的强力执行，以及对各种辅助工具的充分应用，不要写出一大堆难懂、冗余、不规范的代码让将来的自己和同事来帮你填坑。

参考资料：
1. QMUI Web 编码规范