前端代码规范-道乐科技规范系统

前端代码规范

一、前言

前端工程师都应该遵守我们的编码规范，切勿标新立异（即使这很不符合你的编码习惯），这是为了我们可以更好的进行协同合作，提高我们的办公效率

二、HTML5

（一）、语法

1. 用四个空格来代替制表符（tab） -- 这是唯一能保证在所有环境下获得一致展现的方法。

2. 嵌套元素应当缩进一次（即四个空格）。

3. 对于属性的定义，确保全部使用双引号，绝不要使用单引号。

4. 不要在自闭合（self-closing）元素的尾部添加斜线 --HTML5 规范中明确说明这是可选的。

5. 不要省略可选的结束标签（closing tag）（例如，</li>或</body>）。

(二)HTML5 doctype

1. 为每个 HTML 页面的第一行添加标准模式（standard mode）的声明，这样能够确保在每个浏览器中拥有一致的展现。

<!DOCTYPE html>

(三)语言属性

1. 强烈建议为 html 根元素指定 lang 属性，从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等

<html lang="en">
   <--...-->
</html>

(四)IE 兼容模式

1. IE 支持通过特定的标签来确定绘制当前页面所应该采用的 IE 版本。除非有强烈的特殊需求，否则最好是设置为edge mode，从而通知 IE 采用其所支持的最新的模式。

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

2. 要符合响应式网站开发的要求，请在标签中加入如下语句

<meta name="viewport" content="width=device-width, initial-scale=1">

(五)Title

1. 页面必须包含title标签声明标题

<title>新建文件夹</title>

(六）字符编码

1. 通过明确声明字符编码，能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是，可以避免在 HTML 中使用字符实体标记（character entity），从而全部与文档编码一致（一般采用 UTF-8 编码）。

<meta charset="utf-8">

(七)引入 CSS 和 JavaScript 文件

1. 根据 HTML5 规范，在引入 CSS 和 JavaScript 文件时一般不需要指定 type 属性，因为 text/css 和 text/javascript 分别是它们的默认值。

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">
<!-- In-document CSS -->
<style>
/* ... */
</style>
<!-- JavaScript -->
<script src="code-guide.js"></script>

(八) 标签的使用

1. Html中的标签名必须使用小写字母

2. 标签的闭合要符合html5的规定。标签的使用必须符合标签的嵌套规则

3. div不得置于p中，tbody必须置于table中。

4. 标签的使用必须遵循标签的语义，例

a) p -段落

b) h1,h2,h3,h4,h5,h6 - 层级标题

c) strong,em - 强调

d) ins - 插入

e) del -删除

f) abbr - 缩写

g) code - 代码标识

h) cite - 引述来源作品的标题

j) blockquote -一段或长篇引用

k) ul - 无序列表

l) ol - 有序列表

m) dl,dt,dd - 定义列表（建议:在CSS可以实现相同需求的情况下不得使用表格进行布局）

(九) 属性顺序

1. HTML 属性应当按照以下给出的顺序依次排列，确保代码的易读性。

a) class

b) id, name

c) data-*

d) src, for, type, href

e) title, alt

f) aria-*, role

2. class 用于标识高度可复用组件，因此应该排在首位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），因此排在第二位。

(十) 标签命名规则

1. class：必须单词全字母小写，单词间以-分隔，且必须代表相应的模块或部件的内容或功能，不得以html内置样式进行命名，命名应该具有明确的语义。

2. id：必须保持在页面中的唯一性，命名应该具有明确的语义。

(十一) 减少标签的数量

1. 编写 HTML 代码时，尽量避免多余的父元素。很多时候，这需要迭代和重构来实现。请看下面的案例：

<!-- Not so great -->
<span class="avatar">
<img src="..."></span>
<!-- Better -->
<img class="avatar" src="...">

(十二) 避免通过JavaScript 生成的标签

三、 CSS

(一) 语法

1. 用四个空格来代替制表符（tab） -- 这是唯一能保证在所有环境下获得一致展现的方法。

2. 为选择器分组时，将单独的选择器单独放在一行。

3. 为了代码的易读性，在每个声明块的左花括号前添加一个空格。

4. 声明块的右花括号应当单独成行。

5. 每条声明语句的 : 后应该插入一个空格。

6. 为了获得更准确的错误报告，每条声明都应该独占一行。

7. 所有声明语句都应当以分号结尾。最后一条声明语句后面的分号是可选的，但是，如果省略这个分号，你的代码可能更易出错。

8. 对于以逗号分隔的属性值，每个逗号后面都应该插入一个空格（例如，box-shadow）。

9. 不要在 rgb()、rgba()、hsl()、hsla() 或 rect() 值的内部的逗号后面插入空格。这样利于从多个属性值（既加逗号也加空格）中区分多个颜色值（只加逗号，不加空格）。

10. 对于属性值或颜色参数，省略小于 1 的小数前面的 0 （例如，.5 代替 0.5；-.5px 代替 -0.5px）。

11. 十六进制值应该全部小写，例如，#fff。在扫描文档时，小写字符易于分辨，因为他们的形式更易于区分。

12. 尽量使用简写形式的十六进制值，例如，用 #fff 代替#ffffff。

13. 为选择器中的属性添加双引号，例如，input[type="text"]。只有在某些情况下是可选的，但是，为了代码的一致性，建议都加上双引号。

14. 避免为 0 值指定单位，例如，用 margin: 0; 代替margin: 0px;。

(二) 声明顺序

1. 相关的属性声明应当归为一组，并按照下面的顺序排列：

a) Positioning

b) Box model

c) Typographic

d) Visual

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

3. 其他属性只是影响组件的内部（inside）或者是不影响前两组属性，因此排在后面。

(三)不要使用 @import

d) 1. 与标签相比，@import 指令要慢很多，不光增加了额外的请求次数，还会导致不可预料的问题。替代办法有以下几种：

d) 2. 使用多个 <link>元素

3. 通过 Sass 或 Less 类似的 CSS 预处理器将多个 CSS 文件编译为一个文件

4. 通过 Rails、Jekyll 或其他系统中提供过 CSS 文件合并功能

(四)媒体查询（Media query）的位置

1. 将媒体查询放在尽可能相关规则的附近。不要将他们打包放在一个单一样式文件中或者放在文档底部。如果你把他们分开了，将来只会被大家遗忘。下面给出一个典型的实例。

(五) 带前缀的属性

1. 当使用特定厂商的带有前缀的属性时，通过缩进的方式，让每个属性的值在垂直方向对齐，这样便于多行编辑。

(六) 单行规则声明

1. 对于只包含一条声明的样式，为了易读性和便于快速编辑，建议将语句放在同一行。对于带有多条声明的样式，还是应当将声明分为多行。

(七) 简写形式的属性声明

1. 在需要显示地设置所有值的情况下，应当尽量限制使用简写形式的属性声明。

(八) Less 和 Sass 中的嵌套

1. 避免非必要的嵌套。这是因为虽然你可以使用嵌套，但是并不意味着应该使用嵌套。只有在必须将样式限制在父元素内（也就是后代选择器），并且存在多个需要嵌套的元素时才使用嵌套

(九) 注释

1. 代码是由人编写并维护的。请确保你的代码能够自描述、注释良好并且易于他人理解。好的代码注释能够传达上下文关系和代码目的。不要简单地重申组件或 class 名称。

2. 对于较长的注释，务必书写完整的句子；对于一般性注解，可以书写简洁的短语。

(十) class 命名

1. class 名称中只能出现小写字符和破折号（dashe）（不是下划线，也不是驼峰命名法）。破折号应当用于相关 class 的命名（类似于命名空间）（例如，.btn 和 .btn-danger）。

2. 避免过度任意的简写。.btn 代表 button，但是 .s 不能表达任何意思。

3. class 名称应当尽可能短，并且意义明确。

4. 使用有意义的名称。使用有组织的或目的明确的名称，不要使用表现形式（presentational）的名称。

5. 基于最近的父 class 或基本（base） class 作为新 class 的前缀。

6. 使用 .js-* class 来标识行为（与样式相对），并且不要将这些 class 包含到 CSS 文件中

(十一) 选择器

1. 对于通用元素使用 class ，这样利于渲染性能的优化。

2. 对于经常出现的组件，避免使用属性选择器（例如，[class^="..."]）。浏览器的性能会受到这些因素的影响。

3. 选择器要尽可能短，并且尽量限制组成选择器的元素个数，建议不要超过 3 。

4. 只有在必要的时候才将 class 限制在最近的父元素内（也就是后代选择器）（例如，不使用带前缀的 class 时 -- 前缀类似于命名空间）。

(十二) 代码组织

1. 以组件为单位组织代码段。

2. 制定一致的注释规范。

3. 使用一致的空白符将代码分隔成块，这样利于扫描较大的文档。

4. 如果使用了多个 CSS 文件，将其按照组件而非页面的形式分拆，因为页面会被重组，而组件只会被移动

(十三) 编辑器配置

1. 将你的编辑器按照下面的配置进行设置，以避免常见的代码不一致和差异：

a. 用两个空格代替制表符（soft-tab 即用空格代表 tab 符）。

b. 保存文件时，删除尾部的空白符。

c. 设置文件编码为 UTF-8。

d. 在文件结尾添加一个空白行。

四、 JavaScript

(一) JavaScript文件

1. JavaScript程序应独立保存在后缀名为.js的文件中。

2. JavaScript代码不应该被包含在HTML文件中,除非这是段特定只属于此部分的代码。在HTML中的JavaScript代码会明显增加文件大小,而且也不能对其进行缓存和压缩。

(二) 缩进

1. 缩进的单位为两个空格。避免使用Tab键来缩进,也始终没有个统一的Tab长短标准。虽然使用空格会增加文件的大小,但在局域网中几乎可以忽略,且在最小化过程中也可被消除掉。

(三) 每行长度

1. 避免每行超过80个字符。当一条语句一行写不下时,请考虑折行。在运算符号,最好是逗号后换行。在运算符后换行可以减少因为复制粘贴产生的错误被分号掩盖的几率。下一行应该缩进4个空格。

(四) 注释

1. 不要吝啬注释。给以后需要理解你的代码的人们(或许就是你自己)留下信息是非常有用的。注释应该和它们所注释的代码一样是书写良好且清晰明了。偶尔的小幽默就更不错了。记得要避免冗长或者情绪化。

2. 及时地更新注释也很重要。错误的注释会让程序更加难以阅读和理解。

3. 让注释有意义。重点在解释那些不容易立即明白的逻辑上。

(五) 变量声明

1. 所有的变量必须在使用前进行声明。JavaScript并不强制必须这么做,但是这么做可以让程序易于阅读,且也容易发现那些没声明的变量(它们会被编译成全局变量)。

2. 将var语句放在函数的首部，在函数首部定义所有的变量。

3. 最好把每个变量的声明语句单独放到一行,并加上注释说明。所有变量按照字母排序。

4. 尽量减少全局变量的使用，不要让局部变量覆盖全局变量

(六) 函数声明

1. 所有的函数在使用前进行声明。内函数的声明跟在var语句的后面。这样可以帮助判断哪些变量是在函数范围内的。

2. 函数名与“(”(左括号)之间不应该有空格。“)”(右括号)与开始程序体的”{“(左大括号)之间应插入一个空格。函数程序体应缩进四个空格。”}“(右大括号)与声明函数的那一行代码头部对齐。

(七) 命名

1. 变量名应由26个大小写字母(A..Z,a..z),10个数字(0..9),和_(下划线)组成。避免使用国际化字符(如中文),因为它们不是在任何地方都可以被方便的阅读和理解。不要在命名中使用$(美元符号)或者(反斜杠)。

2. 不要把_(下划线)作为变量名的第一个字符。它有时用来表示私有变量,但实际上JavaScript并没提供私有变量的功能。如果私有变量很重要, 那么使用私有成员的形式。应避免使用这种容易让人误解的命名习惯。

3. 大多数的变量名和方法命应以小写字母开头。

4. 必须与new共同使用的构造函数名应以大写字母开头。当new被省略时JavaScript不会有任何编译错误或运行错误抛出。忘记加new时会让不好的事情发生(比如被当成一般的函数),所以大写构造函数名是我们来尽量避免这种情况发生的唯一办法。

5. 全局变量应该全部大写。(JavaScript没有宏或者常量,所以不会因此造成误会)