前言

编写此文档旨在通过代码风格的一致性来降低代码后期维护成本并提高多人协作开发效率，确保团队始终使用简洁和高效的代码

此文档只起到参考和指导作用，除个别强制使用的规则外，开发者可根据自身实际情况自行决定是否遵守，保证团队项目开发大方向一致性即可

基本原则

1.结构、样式、行为分离

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

2.缩进

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

3.文件编码

使用不带 BOM 的 UTF-8 编码

<meta charset="utf-8">

4.注释

HTML:


单行注释

<!-- 文章列表列表模块 -->

多行注释

<!--
@name: Drop Down Menu
@description: Style of top bar drop down menu.
@author: Ashu(Aaaaaashu@gmail.com)
-->

CSS: 组件块和子组件块以及声明块之间使用一空行分隔，子组件块之间三空行分隔

/* =================================================================
   组件块
 ================================================================ */

/* 子组件块
 ================================================================ */
.selector {
  padding: 15px;
  margin-bottom: 15px;
}



/* 子组件块
 =============================================================== */
.selector-secondary {
  display: block; /* 注释*/
}

Javascript:

必须独占一行。// 后跟一个空格，缩进与下一行被注释说明的代码一致
避免使用/* ... */ 这样的多行注释。有多行注释内容时，使用多个单行注释

文件注释: 文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。应该提供文件的大体内容, 它的作者, 依赖关系和兼容性信息。如下:

/**
 * @fileoverview Description of file, its uses and information
 * about its dependencies.
 * @author user@meizu.com (Firstname Lastname)
 * Copyright 2015 Meizu Inc. All Rights Reserved.
 */

HTML编码规范

代码风格

通用约定

HEAD

1.代码风格

1.1 命名

class与id命名使用驼峰命名规则
class 必须代表相应模块或部件的内容或功能，不得以样式信息进行命名
元素 id 必须保证页面唯一，在不影响语义的情况下尽可能简短
同一页面，应避免使用相同的 name 与 id

1.2 标签

标签名必须使用小写字母，尽量减少标签数量
对于无需自闭合的标签，不允许自闭合,如input、br、img、hr 等
对 HTML5 中规定允许省略的闭合标签，不允许省略闭合标签，如li等
标签使用必须符合标签嵌套规则，如div不能嵌套在p里等
在 CSS 可以实现相同需求的情况下不得使用表格进行布局

1.3 语义化

HTML标签的使用遵循其语义

p - 段落

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

strong,em - 强调

ins - 插入

del - 删除

abbr - 缩写

code - 代码标识

cite - 引述来源作品的标题

q - 引用

blockquote - 一段或长篇引用

ul - 无序列表

ol - 有序列表

dl,dt,dd - 定义列表

1.4 属性

属性按照特定的顺序排列以保证易读性

id

class

name

data-xxx

src, for, type, href

title, alt

aria-xxx, role

属性值必须用双引号包围，不允许不使用引号
HTML5规范中disabled,checked,selected等属性不用设置值
自定义属性建议以XXX-为前缀，推荐使用data-

2.通用约定

2.1 DOCTYPE

使用 HTML5 的 doctype 来启用标准模式，建议使用大写的 DOCTYPE
建议在 html 标签上设置正确的 lang 属性
页面必须使用精简形式，明确指定字符编码。指定字符编码的 meta 必须是 head 的第一个直接子元素

2.2 CSS和Javascript引入

引入 CSS 时必须指明 rel="stylesheet"
在 head 中引入页面需要的所有 CSS 资源
JavaScript 应当放在页面末尾，或采用异步加载
引入 CSS 和 JavaScript 时无须指明 type 属性

3.HEAD

3.1 title

页面必须包含 title 标签声明标题
title 必须作为 head 的直接子元素，并紧随 charset 声明之后

<head>
    <meta charset="UTF-8">
    <title>页面标题</title>
</head>

3.2 favicon

在未指定 favicon 时，大多数浏览器会请求 Web Server 根目录下的 favicon.ico 。为了保证 favicon 可访问，避免404，必须遵循以下两种方法之一：

在 Web Server 根目录放置 favicon.ico 文件
使用 link 指定 favicon

<link rel="shortcut icon" href="path/to/favicon.ico">

3.3 viewport

设置可视区域的宽度和初始缩放大小，避免在移动设备上出现页面展示不正常，尽量避免使用绝对定位

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

3.4 Head模版

<!DOCTYPE html>
<html lang="zh-cmn-Hans">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Style Guide</title>
    <meta name="description" content="不超过150个字符">
    <meta name="keywords" content="">
    <meta name="author" content="name, email@gmail.com">

    <!-- 为移动设备添加 viewport -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <!-- iOS 图标 -->
    <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-57x57-precomposed.png">

    <link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml" />
    <link rel="shortcut icon" href="path/to/favicon.ico">
</head>

CSS编程规范

代码风格

性能优化

1.代码风格

1.1 空格

选择器与 { 之间必须包含空格

.selector {
}

属性名与之后的 : 之间不允许包含空格， : 与属性值之间必须包含空格

margin: 0;

列表型属性值书写在单行时，逗号后必须跟一个空格

font-family: Arial, sans-serif;

1.2 选择器

在 >、+、~ 选择器的两边各保留一个空格

/* good */
main > nav {
    padding: 10px;
}

label + input {
    margin-left: 5px;
}

input:checked ~ button {
    background-color: #69C;
}

/* bad */
main>nav {
    padding: 10px;
}

label+input {
    margin-left: 5px;
}

input:checked~button {
    background-color: #69C;
}

使用驼峰命名法为Class和Id命名方式
如无必要，不得为 id、class 选择器添加类型选择器进行限定

/* good */
#error,
.danger-message {
    font-color: #c00;
}

/* bad */
dialog#error,
p.danger-message {
    font-color: #c00;
}

选择器的嵌套层级应不大于 3 级，位置靠后的限定条件应尽可能精确

/* good */
#username input {}
.comment .avatar {}

/* bad */
.page .header .login #username input {}
.comment div * {}

1.3 属性

属性定义必须另起一行
属性定义后必须以分号结尾
在可以使用缩写的情况下，尽量使用属性缩写

/* good */
.post {
    font: 12px/1.5 arial, sans-serif;
}

/* bad */
.post {
    font-family: arial, sans-serif;
    font-size: 12px;
    line-height: 1.5;
}

属性按Positioning->Box model->Typographic->Visual顺序声明

Formatting Model 相关属性包括：position / top / right / bottom / left / float / display / overflow 等

Box Model 相关属性包括：border / margin / padding / width / height 等

Typographic 相关属性包括：font / line-height / text-align / word-wrap 等

Visual 相关属性包括：background / color / transition / list-style 等

示例：

.sidebar {
    /* formatting model: positioning schemes / offsets / z-indexes / display / ...  */
    position: absolute;
    top: 50px;
    left: 0;
    overflow-x: hidden;

    /* box model: sizes / margins / paddings / borders / ...  */
    width: 200px;
    padding: 5px;
    border: 1px solid #ddd;

    /* typographic: font / aligns / text styles / ... */
    font-size: 14px;
    line-height: 20px;

    /* visual: colors / shadows / gradients / ... */
    background: #f5f5f5;
    color: #333;
    -webkit-transition: color 1s;
       -moz-transition: color 1s;
            transition: color 1s;
}

1.4 媒体查询

Media Query 不得单独编排，必须与相关的规则一起定义
Media Query 如果有多个逗号分隔的条件时，应将每个条件放在单独一行中

/* Good */
/* header styles */
@media (...) {
    /* header styles */
}

/* main styles */
@media (...) {
    /* main styles */
}

/* Bad */
/* header styles */
/* main styles */

@media (...) {
    /* header styles */
    /* main styles */
}

2.值与单位

2.1 慎重选择高消耗的样式

高消耗属性在绘制前需要浏览器进行大量计算：

box-shadows

border-radius

transparency

transforms

CSS filters（性能杀手）

2.2 避免过分重排

当发生重排的时候，浏览器需要重新计算布局位置与大小更多详情

常见的重排元素:

width

height

padding

margin

display

border-width

position

top

left

right

bottom

font-size

float

text-align

overflow-y

font-weight

overflow

font-family

line-height

vertical-align

clear

white-space

min-height

2.3 正确使用 Display 的属性

Display 属性会影响页面的渲染，请合理使用。

display: inline后不应该再使用 width、height、margin、padding 以及 float；
display: inline-block 后不应该再使用 float；
display: block 后不应该再使用 vertical-align；
display: table-* 后不应该再使用 margin 或者 float

JavaScirpt 编码规范

简介

这套规范的主体是基于 JavaScript Stardard Style 的内容基于自身的业务需要和情况来进行自我定制和更新。

重点

1. 缩进

使用两个空格进行缩进。

function hello(name) {
  console.log('hi', name)
}

2. 命名

对于变量和函数名统一使用驼峰命名法。

function my_function() {} // ✗ avoid
function myFunction() {} // ✓ ok

var my_var = 'hello' // ✗ avoid
var myVar = 'hello' // ✓ ok

私有属性、变量和方法以下划线 _ 开头。
```
var _privateMethod = {};`
```

类使用 Pascal 命名法。

```js
function TextNode(value, engine) {
  this.value = value
  this.engine = engine
}
```

类的方法 / 属性, 使用 Camel 命名法。

TextNode.prototype.clone = function() {
  return this
}

常量：必须全部大写，且单词以 _分割。

TextNode.prototype.clone = function() {
  return this
}

boolean 类型的变量使用 is 或 has 开头。

var HOTEL_GET_URL = 'http://map.baidu.com/detail'

3. 注释。

```
// 单行注释
/*
*hello
*world
*/
```
说明： 若开始`/*`和结束`*/`都在一行，推荐采用单行注释。若至少三行注释时，第一行为`/*`，最后行为`*/`，其他行以*开始，并且注释文字与`*`保留一个空格。

4. 不要使用 `eval()`

eval('var result = user.' + propName) // ✗ avoid
var result = user[propName] // ✓ ok

细则

JavaScript Stardrad Style

使用

使用 Eslint,配置为 Standrd.

extends: 'standard',

后续？

函数命名语义规范
变量语义规范
编码原则

前端编程规范文档

前言

基本原则

1.结构、样式、行为分离

2.缩进

3.文件编码

4.注释

HTML编码规范

1.代码风格

1.1 命名

1.2 标签

1.3 语义化

1.4 属性

2.通用约定

2.1 DOCTYPE

2.2 CSS和Javascript引入

3.HEAD

3.1 title

3.2 favicon

3.3 viewport

3.4 Head模版

CSS编程规范

1.代码风格

1.1 空格

1.2 选择器

1.3 属性

1.4 媒体查询

2.值与单位

2.1 慎重选择高消耗的样式

2.2 避免过分重排

2.3 正确使用 Display 的属性

JavaScirpt 编码规范

简介

重点

1. 缩进

2. 命名

3. 注释。

4. 不要使用 eval()

细则

使用

后续？

4. 不要使用 `eval()`