网站开发之前端代码规范
前端代码规范
-
- 前言
- 一、唯一定律
- 二、前段代码规范
-
- （一）命名规范
-
- 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单行注释
一般用于简单的描述，如某些状态描述、属性描述等
注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行
推荐：
<div>...div>
不推荐：
<div>...div>
<div>
...
div>
1.5.2、HTML模块注释
一般用于描述模块的名称以及模块开始与结束的位置
注释内容前后各一个空格字符，表示模块开始， 表示模块结束，模块与模块之间相隔一行
推荐写法：
<div class="mod_a">
...
div>
<div class="mod_b">
...
div>
不推荐写法：
<div class="mod_a">
...
div>
<div class="mod_b">
...
div>
1.5.3、HTML嵌套模块注释
当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用
而改用
注释写在模块结尾标签底部，单独一行。
<div class="mod_a">
<div class="mod_b">
...
div>
<div class="mod_c">
...
div>
div>
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 大写
正例：
<html lang="zh">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta charset="UTF-8" />
<title>Page titletitle>
head>
<body>
<img src="images/company-logo.png" alt="Company" />
body>
html>
2.2 、缩进
前端缩进统一使用 2 个空格（可将一个html、css、js等文件设置一个tab为两个空格）
嵌套的节点应该缩进。
2.3、分块注释
在每一个块状元素，列表元素和表格元素后，加上一对 HTML 注释。注释格式
正例：
<body>
<header>
<div class="container">
<a href="#">
<img src="images/header.jpg" />
a>
div>
header>
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;
}
推荐:
.heavy {
font-weight: 800;
}
.important {
color: red;
}
3.2、选择器
1)、css 选择器中避免使用标签名
从结构、表现、行为分离的原则来看，应该尽量避免 css 中出现 HTML 标签，并且在 css 选择器中出现标签名会存在潜在的问题。
2)、很多前端开发人员写选择器链的时候不使用 直接子选择器（注：直接子选择器和后代选择器的区别）。有时，这可能会导致疼痛的设计问题并且有时候可能会很耗性能。然而，在任何情况下，这是一个非常不好的做法。如果你不写很通用的，需要匹配到 DOM 末端的选择器， 你应该总是考虑直接子选择器。
不推荐:
.content .title {
font-size: 2rem;
}
推荐:
.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 = '';
反例:
let str = 'foo';
let testDiv = "";
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 功能