网站开发之前端代码规范

前端代码规范

前言
一、唯一定律
二、前段代码规范
- （一）命名规范
- - 1.1、项目命名
  - 1.2 、目录命名
  - 1.3、文件存放位置
  - 1.4、JS、CSS、HTML、PNG 等文件命名
  - 1.4、命名严谨性
  - 1.5、代码注释
  - - 1.5.1、HTML单行注释
    - 1.5.2、HTML模块注释
    - 1.5.3、HTML嵌套模块注释
    - 1.5.4、CSS单行注释
    - 1.5.5、模块注释
- （二）HTML 规范
- - 2.1 、HTML 类型
  - 2.2 、缩进
  - 2.3、分块注释
  - 2.4、语义化标签
  - 2.5、引号
  - 2.6、闭合标签
  - 2.7、引入CSS和JavaScript
  - 2.8、属性顺序
  - 2.9、布尔型属性
  - 2.10、减少标签的数量
  - 2.11、减少 JavaScript 生成的标签
  - 2.12、提示
- （三） CSS 规范
- - 3.1、命名
  - 3.2、选择器
  - 3.3、尽量使用缩写属性
  - 3.4、选择器及属性独占一行
  - 3.5、省略0后面的单位
  - 3.6、避免使用ID选择器
  - 3.7、分号结尾
  - 3.8、省略 0.X前面的0
  - 3.9、十六进制值全部小写
  - 3.10、属性声明顺序
  - 3.11、重置样式
- （四）JavaScript规范
- - 4.1、命名
  - 4.2、代码格式
  - 4.3 、字符串
  - 4.4、对象声明
  - 4.5、使用 ES6,7
  - 4.6、括号
  - 4.7、分号
  - 4.8、空格
  - 4.9、undefined 判断
  - 4.10、条件判断和循环最多三层
  - 4.11、慎用 console.log

前言

最近自己想开发一个网站，所以编写了前端和java的响应的代码规范，其实都是整合别人的觉得合适的规范。
本规范的目的是为了编写灵活、稳定、高质量的代码，让每个团队成员每天得心情都是愉悦的，一起开心的coding

一、唯一定律

无论有多少人共同参与同一项目，一定要确保每一行代码都像是唯一个人编写的。

二、前段代码规范

（一）命名规范

1.1、项目命名

全部采用小写方式，以中划线分隔。

正例：cust-relation-system

反例：cust_relation_system / custRelationSystem

1.2 、目录命名

全部采用小写方式，以中划线分隔，有复数结构时，要采用复数命名法，缩写不用复数

正例： scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc

反例： script / style / demo_scripts / demoStyles / imgs / docs

1.3、文件存放位置

文件夹名称	文件夹含义
image	存放图片文件
media	存放多媒体文件
library	第三方依赖包
js	存放JavaScript脚本
css	存放CSS文件

1.4、JS、CSS、HTML、PNG 等文件命名

全部采用小写方式，以中划线分隔

正例： render-dom.js / signup.css / index.html / company-logo.png

反例： renderDom.js / UserManagement.html

1.4、命名严谨性

代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用

正例：shanghai / beijing / rmb 等国际通用的名称，可视同英文。

反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

杜绝完全不规范的缩写，避免望文不知义：

反例：condition“缩写”命名成 condi，此类随意缩写严重降低了代码的可阅读性。

1.5、代码注释

代码内文档在软件设计中起着至关重要的作用。 注释对于帮助开发人员理解系统和有效地工作是必不可少的，但是注释的作用远远不止于此。文档在抽象中也扮演着重要的角色;没有注释，就无法隐藏复杂性。最后，编写注释的过程如果处理正确，实际上将改进系统的设计。相反，如果没有良好的文档记录，好的软件设计就会失去很多价值。

我们要保持良好的注释习惯，保证程序的可阅读性，好的程序应首先易于阅读，其次才是效率高低的问题。

1.5.1、HTML单行注释

一般用于简单的描述，如某些状态描述、属性描述等

注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行

推荐：

<!-- Comment Text -->
<div>...</div>

不推荐：

<div>...</div><!-- Comment Text -->    <div><!-- Comment Text -->...
</div>

1.5.2、HTML模块注释

一般用于描述模块的名称以及模块开始与结束的位置

注释内容前后各一个空格字符，表示模块开始， 表示模块结束，模块与模块之间相隔一行

推荐写法：

<!-- S Comment Text A -->
<div class="mod_a">...
</div>
<!-- E Comment Text A --><!-- S Comment Text B -->
<div class="mod_b">...
</div>
<!-- E Comment Text B -->

不推荐写法：

<!-- S Comment Text A -->
<div class="mod_a">...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->
<div class="mod_b">...
</div>
<!-- E Comment Text B -->

1.5.3、HTML嵌套模块注释

当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用

<!-- S Comment Text -->
<!-- E Comment Text -->

而改用

<!-- /Comment Text -->

注释写在模块结尾标签底部，单独一行。

<!-- S Comment Text A -->
<div class="mod_a"><div class="mod_b">...</div><!-- /mod_b --><div class="mod_c">...</div><!-- /mod_c --></div>
<!-- E Comment Text A -->

1.5.4、CSS单行注释

注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行

推荐：

/* Comment Text */
.xiaoming {}/* Comment Text */
.xiaoming {}

不推荐：

/*Comment Text*/
.xiaoming {display: block;
}
.xiaoming {display: block;/*Comment Text*/
}

1.5.5、模块注释

注释内容第一个字符和最后一个字符都是一个空格字符，/* 与模块信息描述占一行，多个横线分隔符-与*/占一行，行与行之间相隔两行

推荐：

/* Module A
---------------------------------------------------------------- */
.mod_a {}/* Module B
---------------------------------------------------------------- */
.mod_b {}

不推荐：

/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}

（二）HTML 规范

2.1 、HTML 类型

推荐使用 HTML5 的文档类型申明：（建议使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的属性，比如 application/xhtml+xml 在浏览器中的应用支持与优化空间都十分有限）。

语言属性
规定字符编码
IE 兼容模式
规定字符编码
doctype 大写

正例：

<!DOCTYPE html>
<html lang="zh"><head><meta http-equiv="X-UA-Compatible" content="IE=Edge" /><meta charset="UTF-8" /><title>Page title</title></head><body><img src="data:images/company-logo.png" alt="Company" /></body>
</html>

2.2 、缩进

前端缩进统一使用 2 个空格（可将一个html、css、js等文件设置一个tab为两个空格）

嵌套的节点应该缩进。

2.3、分块注释

在每一个块状元素，列表元素和表格元素后，加上一对 HTML 注释。注释格式

正例：

<body><!-- header 头部 start --><header><div class="container"><a href="#"><!-- 图片会把a标签给撑开，所以不用设置a标签的大小 --><img src="data:images/header.jpg" /></a></div></header><!-- header 头部 end -->
</body>

2.4、语义化标签

HTML5 中新增很多语义化标签，所以优先使用语义化标签，避免一个页面都是 div 或者 p 标签

正例

<header></header>
<footer></footer>

反例

<div><p></p>
</div>

2.5、引号

使用双引号(" ") 而不是单引号(’ ') 。

正例： “xiaoming”

反例： ‘xiaoming’

2.6、闭合标签

不要在自闭合（self-closing）元素的尾部添加斜线( / ) –HTML5 规范中明确说明这是可选的
不要省略可选的结束标签（closing tag）（例如，
或）

2.7、引入CSS和JavaScript

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

正例

<link rel="stylesheet" href="index.css">
<script src="index.js"></script>

反例

<link type="text/css" rel="stylesheet" href="index.css">
<script type="text/javascript" src="index.js"></script>

2.8、属性顺序

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

（1）class

（2）id, name

（3）data-*

（4）src, for, type, href, value

（5）title, alt

（6）role, aria-*

例子

<a class="" id="" data-ref="" href=""></a>
<input class="" type="text">
<img src="" alt="">

2.9、布尔型属性

1）布尔型属性可以在声明时不赋值。XHTML 规范要求为其赋值，但是 HTML5 规范不需要。

2）元素的布尔型属性如果有值，就是 true，如果没有值，就是 false。

3）如果属性存在，其值必须是空字符串或 […] 属性的规范名称，并且不要在首尾添加空白符。
简单来说，就是不用赋值。

2.10、减少标签的数量

编写 HTML 代码时，尽量避免多余的父元素。

2.11、减少 JavaScript 生成的标签

通过 JavaScript 生成的标签让内容变得不易查找、编辑，并且降低性能。能避免时尽量避免。

2.12、提示

尽量遵循 HTML 标准和语义，但是不要以牺牲实用性为代价。任何时候都要尽量使用最少的标签并保持最小的复杂度。

（三） CSS 规范

3.1、命名

类名使用小写字母，以中划线分隔
id 采用驼峰式命名

id 和 class 的名称使用可以反应元素目的和用途的名称，或其他通用的名称，代替表象和晦涩难懂的名称

不推荐：

.fw-800 {font-weight: 800;
}.red {color: red;
}

3.2、选择器

1)、css 选择器中避免使用标签名
从结构、表现、行为分离的原则来看，应该尽量避免 css 中出现 HTML 标签，并且在 css 选择器中出现标签名会存在潜在的问题。

2)、很多前端开发人员写选择器链的时候不使用直接子选择器（注：直接子选择器和后代选择器的区别）。有时，这可能会导致疼痛的设计问题并且有时候可能会很耗性能。然而，在任何情况下，这是一个非常不好的做法。如果你不写很通用的，需要匹配到 DOM 末端的选择器，你应该总是考虑直接子选择器。

不推荐:

.content .title {font-size: 2rem;
}

3.3、尽量使用缩写属性

不推荐：

border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;

推荐：

border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;

3.4、选择器及属性独占一行

不推荐：

button {width:100px;height:50px;color:#fff;background:#00a0e9;
}

推荐：

button {width:100px;height:50px;color:#fff;background:#00a0e9;
}

3.5、省略0后面的单位

不推荐：

div {padding-bottom: 0px;margin: 0em;
}

推荐：

div {padding-bottom: 0;margin: 0;
}

3.6、避免使用ID选择器

不推荐：

#xiaoming {padding-bottom: 0px;margin: 0em;
}

推荐：

.xiaoming {padding-bottom: 0px;margin: 0em;
}

3.7、分号结尾

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

3.8、省略 0.X前面的0

对于属性值或颜色参数，省略小于 1 的小数前面的 0

例

.xiaoming {box-shadow: 0 1px 1px 1px rgba(0, 0, 0, .5);
}

3.9、十六进制值全部小写

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

2）、尽量使用简写形式的十六进制值，例如，用 #fff 代替 #ffffff

3.10、属性声明顺序

（1）文档流相关属性（display, position, float, clear, visibility, table-layout）

（2）盒模型相关属性（width, height, margin, padding, border）

（3）排版相关属性（font, line-height, text-align, text-indent, vertical-align）

（4）装饰性相关属性（color, background, opacity, cursor）

（5）文字排版（font, line-height, letter-spacing, color- text-align）

（6）生成内容相关属性（background, border）

说明、

上面并没有列举涵盖所有的属性，只是一部分
分类之间使用一个空行分隔
并不一定严格遵循上述原则，因为这是一个最佳实践，与标准和性能无关

例子

 .xiaoming {/* 全局属性 */display: block;float: none;list-style: none;/* 定位属性 */position: absolute;left: 0;top: 0;right: 0;bottom: 0;z-index: 0;/* 基本属性 */box-sizing: border-box;margin: 0 auto;padding: 0;width: inherit;min-width: none;max-width: none;height: inherit;min-height: inherit;max-height: none;border: none;border-radius: inherit;/* 基础效果属性 */font: '微软雅黑';font-size: 12px;font-style: inherit;font-family: 'new york';font-weight: bold;line-height: 32px;text-align: center;vertical-align: middle;white-space: normal;letter-spacing: normal;word-spacing: normal;word-break: break-all;/* 背景属性 */color: #000000;background: no-repeat;background-clip: inherit;background-color: #000000;background-origin: border-box;background-size: cover;background-position: left top;/* 渲染效果属性 */opacity: inherit;outline: none;box-shadow: none;transition: all;transform: inherit;animation: .25s, 100ms;/* 其他属性 */cursor: pointer;}

3.11、重置样式

css重置样式主要是为了让各个浏览器的CSS样式有一个统一的基准，使HTML元素样式在跨浏览器时有一致性的效果。

备注：浏览器的兼容问题，不同浏览器对有些标签的默认值是不同的，如果不对css初始化往往会出现浏览器之间的页面显示差异。但是初始化样式也会对SEO有一定的影响，故初始化时尽量使影响最小。

/* 淘宝的重置样式代码 */
body, h1, h2, h3, h4, h5, h6, hr, p, blockquote, dl, dt, dd, ul, ol, li, pre, form, fieldset, legend, button, input, textarea, th, td { margin:0; padding:0; }
body, button, input, select, textarea { font:12px/1.5tahoma, arial, \5b8b\4f53; }
h1, h2, h3, h4, h5, h6{ font-size:100%; }
address, cite, dfn, em, var { font-style:normal; }
code, kbd, pre, samp { font-family:couriernew, courier, monospace; }
small{ font-size:12px; }
ul, ol { list-style:none; }
a { text-decoration:none; }
a:hover { text-decoration:underline; }
sup { vertical-align:text-top; }
sub{ vertical-align:text-bottom; }
legend { color:#000; }
fieldset, img { border:0; }
button, input, select, textarea { font-size:100%; }
table { border-collapse:collapse; border-spacing:0; }

（四）JavaScript规范

4.1、命名

1) 、采用小写驼峰命名 lowerCamelCase，代码中的命名均不能以下划线开始，也不能以下划线或美元符号结束

反例： _name / name_ / name$

2) 、方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。

正例： localValue / getHttpMessage() / inputUserId

其中 method 方法命名必须是动词或者动词+名词形式

正例：saveShopCarData /openShopCarInfoDialog

反例：save / open / show / go

特此说明，增删查改，详情统一使用如下 4个单词，不得使用其他（目的是为了统一各个端）

add / delete / update / get

附：函数方法常用的动词:

get 获取/set 设置,
add 增加/remove 删除
create 创建/destory 移除
start 启动/stop 停止
open 打开/close 关闭,
read 读取/write 写入
load 载入/save 保存,
create 创建/destroy 销毁
begin 开始/end 结束,
backup 备份/restore 恢复
import 导入/export 导出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附着/detach 脱离
bind 绑定/separate 分离,
view 查看/browse 浏览
edit 编辑/modify 修改,
select 选取/mark 标记
copy 复制/paste 粘贴,
undo 撤销/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 减少
play 播放/pause 暂停,
launch 启动/run 运行
compile 编译/execute 执行,
debug 调试/trace 跟踪
observe 观察/listen 监听,
build 构建/publish 发布
input 输入/output 输出,
encode 编码/decode 解码
encrypt 加密/decrypt 解密,
compress 压缩/decompress 解压缩
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 连接/disconnect 断开,
send 发送/receive 接收
download 下载/upload 上传,
refresh 刷新/synchronize 同步
update 更新/revert 复原,
lock 锁定/unlock 解锁
check out 签出/check in 签入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展开/collapse 折叠
begin 起始/end 结束,
start 开始/finish 完成
enter 进入/exit 退出,
abort 放弃/quit 离开
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集

3) 、常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

正例： MAX_STOCK_COUNT

反例： MAX_COUNT

4.2、代码格式

1) 、使用 2 个空格进行缩进

正例：

if (x < y) {x += 10;
} else {x += 1;
}

2)、不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

说明：任何情形，没有必要插入多个空行进行隔开。

4.3 、字符串

统一使用单引号(‘)，不使用双引号(“)。这在js中创建 HTML 字符串非常有好处：

正例:

let str = 'foo';
let testDiv = '<div id="test"></div>';

反例:

let str = 'foo';
let testDiv = "<div id='test'></div>";

4.4、对象声明

1)、使用字面值创建对象

正例： let user = {};

反例： let user = new Object();

2) 、使用字面量来代替对象构造器

正例：

var user = {age: 0,name: 1,city: 3
};

反例：

var user = new Object();
user.age = 0;
user.name = 0;
user.city = 0;

4.5、使用 ES6,7

必须优先使用 ES6,7 中新增的语法糖和函数。这将简化你的程序，并让你的代码更加灵活和可复用。

必须强制使用 ES6, ES7 的新语法，比如箭头函数、await/async ，解构， let ， for…of 等等

4.6、括号

下列关键字后必须有大括号（即使代码块的内容只有一行）：if, else, for, while, do, switch, try, catch, finally, with。

正例：

if (condition) {doSomething();
}

反例：

if (condition) doSomething();

4.7、分号

每句代码后（必须）加";"

4.8、空格

左括号和后一个字符之间不出现空格；同样，右括号和前一个字符之间也不出现空格
if/for/while/do 等保留字与左右括号之间都**（必须）**加空格，switch后无需加空格
function 后**（必须）加空格，参数的反括号后（必须）**加空格
声明变量 = 前后**（必须）**添加空格
每个;后**（必须）**加空格
任何运算符左右必须加一个空格。说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号、三目运行符等
```
function add(xiaoming) {if (typeof xiaoming === 'undefined') {// code}
}
```

4.9、undefined 判断

永远不要直接使用 undefined 进行变量判断；使用 typeof 和字符串’undefined’对变量进行判断。

正例：

if (typeof person === 'undefined') {...
}

反例：

if (person === undefined) {...
}

4.10、条件判断和循环最多三层

条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但是谨记不要写太长的三目运算符。如果超过 3 层请抽成函数，并写清楚注释。

4.11、慎用 console.log

因 console.log 大量使用会有性能问题，所以在非 webpack 项目中谨慎使用 log 功能