开发规范

一．HTML规范

1. 基本原则

• 结构、样式、行为分离
  尽量确保文档和模板只包含 HTML 结构，样式都放到样式表里，行为都放到脚本里。

• 缩进
  统一两个空格缩进（总之缩进统一即可），不要使用 Tab 或者 Tab、空格混搭。

• 文件编码
  使用不带 BOM 的 UTF-8 编码。在 HTML中指定编码<meta charset="utf-8">；无需使用 @charset指定样式表的编码，它默认为UTF-8（参考 @charset）；

• 一律使用小写字母

image.png

• 注释

  • 统一注释
    通过配置编辑器，可以提供快捷键来输出一致认可的注释模式。
    例如：VS code 快捷键 ctrl+/

<!-- Recommended -->

注释内容左右两边保留和注释符号有1个空格位，在注释内容内不允许再出现中划线-

• 按模块添加注释
  image.png

  注释风格保持与原生HTML的语法相似：成对出现

<!-- comment --><!-- /comment -->

2. HTML 相关

• 标签

  • 自闭合（self-closing）标签，无需闭合 ( 例如： img input br hr 等 )；
  • 可选的闭合标签（closing tag），需闭合 ( 例如：</li> 或 </body> )；
  • 尽量减少标签数量；

• 格式

  • 将每个块元素、列表元素或表格元素都放在新行；
  • inline元素视情况换行，以长度不超过编辑器一屏为宜；

  • 每个子元素都需要相对其父级缩进（参见缩进约定）。

    
    
    image.png

• 模块化

• 每个模块必须有一个模块名；

• 每个模块的基本组成部分应该一致；

• 模块的子节点类名需带上模块名（防止模块间嵌套时产生不必要的覆盖）；

• 孙辈节点无需再带模块名。

  image.png
  其中.m-detail-hd, .m-detail-bd, .m-detail-ft为可选，视具体模块情况决定是否需要抽象为这种 头，中，尾 的结构

• class 与 id

  • class 应以功能或内容命名，不以表现形式命名；
  • class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔，不要驼峰命名法和下划线；
  • 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class；

• 属性顺序
  HTML 属性应该按照特定的顺序出现以保证易读性。
  id > class > name > data-xxx > src,for,type,href > title,alt > aria-xxx,role

• 引号
  

  属性的定义，统一使用双引号。
  image.png

• 嵌套
  a 不允许嵌套 div这种约束属于语义嵌套约束，与之区别的约束还有严格嵌套约束，比如a 不允许嵌套 a。
  严格嵌套约束在所有的浏览器下都不被允许；而语义嵌套约束，浏览器大多会容错处理，生成的文档树可能相互不太一样。
  语义嵌套约束

  • <li>用于<ul> 或<ol> 下；
  • <dd>, <dt> 用于 <dl> 下；
  • <thead>, <tbody>, <tfoot>, <tr>, <td> 用于 <table> 下；
    严格嵌套约束
  • inline-Level 元素，仅可以包含文本或其它 inline-Level 元素;
  • <a>里不可以嵌套交互式元素<a>、<button>、<select>等;
  • <p>里不可以嵌套块级元素<div>、<h1>~<h6>、<p>、<ul>/<ol>/<li>、<dl>/<dt>/<dd>、<form>等。

更多详情，参考WEB标准系列-HTML元素嵌套

• 布尔值属性
  HTML5 规范中 disabled、checked、selected 等属性不用设置值。
  image.png
• 语义化
  没有 CSS 的 HTML 是一个语义系统而不是 UI 系统。通常情况下，每个标签都是有语义的，各自有对应的功能和含义。语义化的 HTML 结构，有助于机器（搜索引擎）理解，另一方面多人协作时，能迅速了解开发者意图。

• head
  

  文档类型。为每个 HTML 页面的第一行添加标准模式（standard mode）的声明， 这样能够确保在每个浏览器中拥有一致的表现。
  image.png
• 语言属性
  lang属性的取值应该遵循BCP 47 - Tags for Identifying Languages。
  image.png
• 字符编码
  • 以无 BOM 的 utf-8 编码作为文件格式;
  • 指定字符编码的 meta 必须是 head 的第一个直接子元素；
    image.png

• IE 兼容模式
  

  优先使用最新版本的IE 和 Chrome 内核
  image.png

• SEO 优化
  image.png
• viewport
  • viewport: 一般指的是浏览器窗口内容区的大小，不包含工具条、选项卡等内容；
  • width: 浏览器宽度，输出设备中的页面可见区域宽度；
  • device-width: 设备分辨率宽度，输出设备的屏幕可见宽度；
  • initial-scale: 初始缩放比例；
  • maximum-scale: 最大缩放比例；

image.png

• head模板
  image.png

二．CSS 规范

1. class和id

• class应以功能或内容命名，不以表现形式命名；
• class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔，不要驼峰命名法和下划线；
• 使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class；
• 避免选择器和 Class、ID 叠加使用；
• 避免选择器嵌套层级过多，尽量少于 3 级；
• 重构工程师只允许使用class；

出于性能考量，在没有必要的情况下避免元素选择器叠加 Class、ID 使用。元素选择器和ID、Class 混合使用也违反关注点分离原则。如果HTML标签修改了，就要再去修改 CSS 代码，不利于后期维护。

2. 命名规范

• 组成元素
  • 【强制】命名必须由小写单词、中划线-组成。不允许使用大写字母或_、不允许通过1、2、3等序号进行命名
  • 【强制】不允许使用拼音（约定俗成的除外，如：youku, baidu），尤其是缩写的拼音、拼音与英文的混合。应该采用更简明有语义的英文单词进行组合,应该用意义命名，而不是样式显示结果命名;不要用抽象的晦涩的命名.
    image.png
• 词汇规范
  • 不依据表现形式来命名；
  • 可根据内容来命名；

  • 可根据功能来命名；
    image.png
• 缩写规范
  • 保证缩写后还能较为清晰保持原单词所能表述的意思；

  • 使用业界熟知的或者约定俗成的；
    image.png
• 前缀规范

image.png

3. 书写格式

• 【强制】选择器与大括号之间保留一个空格；
• 【强制】分号之后保留一个空格；
• 【强制】逗号之后保留一个空格；
• 【强制】所有规则需换行；
• 【强制】多组选择器之间需换行；
• 【强制】使用单引号，不允许使用双引号；
• 【强制】除字体设置外，CSS文件中的所有的代码都应该小写；
• 【强制】除了重置浏览器默认样式外，禁止直接为html tag添加css样式设置;
• 【强制】每一条规则应该确保选择器唯一，禁止直接为全局.nav、.header、.body等类设置属性;

4. 书写规则

• 【强制】每条规则结束后都必须加上分号；
• 如果属性值为0，则不需要为0加单位；
• HEX颜色值写法：将所有的颜色值小写，可以缩写的缩写至3位。

5. 注释规范

• 保持注释内容与星号之间有一个空格的距离。

• 文件顶部注释
  image.png

• 单行注释

  
  
  image.png

• 模块注释
  

  模块注释必须单独写在一行
  image.png
• 单行注释与多行注释,单行注释可以写在单独一行，注释中的每一行长度不超过40个汉字，或者80个英文字符。

• 特殊注释
  

  用于标注修改、待办等信息
  image.png

6. 声明顺序

相关属性应为一组，推荐的样式编写顺序

• Positioning定位：可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式
• Box model盒模型：决定了一个组件的大小和位置
• Typographic 排版
• Visual 外观

由于定位（positioning）可以从正常的文档流中移除元素，并且还能覆盖盒模型（box model）相关的样式，因此排在首位。盒模型决定了组件的尺寸和位置，因此排在第二位。

image.png

三．JS规范

1. 命名规范

• 【强制】代码中命名不能以下划线或美元符开始，也不能以下划线或美元符结束
• 【强制】代码中严禁使用拼音与英文混合的方式，更不允许直接使用中文方式。纯拼音命名方式也要避免采用（国际通用的名称可视为英文，如：taobao，alibaba等）
• 【强制】类名使用UpperCamelCase风格，使用名词
  image.png
  image.png
• 私有属性、变量和方法以下划线_开头。

• 私有属性、变量和方法以下划线_开头。
  image.png
• 【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式 如：localValue，getMessage()。方法名使用动宾短语。
  image.png
  image.png
  image.png

• 【强制】常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长
  image.png
• boolean 类型的变量使用 is 或 has 开头。
  image.png
• Promise 对象用动宾短语的进行时表达。
  image.png
• 【强制】杜绝完全不规范的缩写，避免望文不知义
• let、const与var
  ES6 新增了let命令，用来声明变量。它的用法类似于var，但是所声明的变量，只在let命令所在的代码块内有效。
  工程开发中，除部分常量使用const声明外，其余全部使用let，不使用var；
  var有以下缺点：变量提升。不适合循环等局部运算(容易导致很多无法预料的结果)
• 【推荐】为了达到代码自解释的目标，任何定义编程元素在命名时使用尽量完整单词组合来表达其意

2. 注释规范

• 【强制】类，类属性，类方法使用/**内容*/格式，不得使用// xxx方式
• 单行注释
  必须独占一行。//后跟一个空格，缩进与下一行被注释说明的代码一致。
• 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。参数和返回值注释必须包含类型信息和说明，当函数是内部函数，外部不可访问时，可以使用 @inner 标识。方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
  image.png
• 代码修改同时，注释也要进行相应修改，尤其是参数、返回值、核心逻辑等的修改。说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。
• 特殊注释标记
  请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
  待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]） 表示需要实现，但目前还未实现的功能。
  错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]） 在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

3. 风格规范

• 空格与运算符
  通常运算符 ( = + - * / ) 前后需要添加空格，任何二目、三目运算符的左右两边都需要加一个空格。
  image.png

• 一条语句通常以分号作为结束符。
  image.png
• 复杂语句的通用规则:
  • 将左花括号放在第一行的结尾。
  • 左花括号前添加一空格。
  • 将右花括号独立放在一行。
  • 不要以分号结束一个复杂的声明。

image.png

• 对象规则
  • 将左花括号与类名放在同一行。
  • 冒号与属性值间有个空格。
  • 字符串使用双引号，数字不需要。
  • 最后一个属性-值对后面不要添加逗号。
  • 将右花括号独立放在一行，并以分号作为结束符号

image.png

四．Vue规范

1. 详见：https://cn.vuejs.org/v2/style-guide/