编码规范
本规范参考了 Google 前端代码规范和腾讯的前端团队规范文档,在此致谢。
Notes:我们在着手 Admui 开发之初,参考 Google 前端代码规范和腾讯的前端团队规范文档制定了这套规范,并尽量遵循使其代码保持美观一致的风格,为 Admui 的健康发展和团队协作奠定了基础,在此向他们致谢。但是Admui中包含的第三方代码(如 Bootstrap,jQuery,第三方插件库等)除外。我们推荐您也遵循或者部分遵循这套开发规范,以避免不必要的麻烦和提高开发效率。
命名规则
项目命名
全部采用小写方式, 以中划线分隔。如:my-project-name
。
目录命名
- 参照项目命名规则;
- 有复数结构时,要采用复数命名法。例:
images
,data-models
。
JS文件命名
参照项目命名规则。例:account-model.js
。
CSS, LESS文件命名
参照项目命名规则。例:retina-sprites.less
。
HTML文件命名
参照项目命名规则。例:error-report.html
。
HTML编码规范
语法
- 使用Tab缩进(4个空格);
- 嵌套的节点应该缩进;
- 在属性上,使用双引号,不要使用单引号;
- 属性名全小写,用中划线做分隔符;
- 不要在自动闭合标签结尾处使用斜线(HTML5规范指出他们是可选的);
- 不要忽略可选的关闭标签,例:
</li>
和</body>
。
<!DOCTYPE html> |
HTML5 doctype
- 在页面开头使用这个简单地doctype来启用标准模式,使其在每个浏览器中尽可能一致的展现;
- 虽然doctype不区分大小写,但是按照惯例,doctype大写(关于html属性,大写还是小写)。
<!DOCTYPE html> |
lang属性
根据HTML5规范:
应在html标签上加上lang属性。这会给语音工具和翻译工具帮助,告诉它们应当怎么去发音和翻译。
- 更多关于
lang
属性的说明在 这里; - 在sitepoint上可以查到 语言列表;
- 但sitepoint只是给出了语言的大类,例如中文只给出了
zh
,但是没有区分香港,台湾,大陆。而微软给出了一份更加详细的 语言列表,其中细分了zh-cn
,zh-hk
,zh-tw
。
<!DOCTYPE html> |
字符编码
通过声明一个明确的字符编码,让浏览器轻松、快速的确定适合网页内容的渲染方式,通常指定为utf-8
。
<!DOCTYPE html> |
IE兼容模式
<!DOCTYPE html> |
引入CSS, JS
根据HTML5规范, 通常在引入CSS和JS时不需要指明type
,因为text/css
和text/javascript
分别是他们的默认值。
HTML5 规范链接
<!-- 外联 CSS --> |
属性顺序
- 属性应该按照特定的顺序出现以保证易读性;
class
;id
;name
;data-*
;src
,for
,type
,href
,value
,max-length
,max
,min
,pattern
;placeholder
,title
,alt
;aria-*
,role
;required
,readonly
,disabled
。
class
是为高可复用组件设计的,所以应处在第一位;id
更加具体且应该尽量少使用,所以将它放在第二位。
<a class="..." id="..." data-modal="toggle" href="#">Example link</a> |
boolean属性
boolean
属性指不需要声明取值的属性,XHTML需要每个属性声明取值,但是HTML5并不需要;- 更多内容可以参考 What WG section on boolean attributes:
Notes:boolean属性的存在表示取值为true,不存在则表示取值为false。
<input type="text" disabled> |
JS生成标签
在JS文件中生成标签让内容变得更难查找,更难编辑,性能更差。应该尽量避免这种情况的出现。
减少标签数量
- 在编写HTML代码时,需要尽量避免多余的父节点;
- 很多时候,需要通过迭代和重构来使HTML变得更少。
<!-- 不推荐写法 --> |
实用高于完美
- 尽量遵循HTML标准和语义,但是不应该以浪费实用性作为代价;
- 任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。
CSS, LESS 编码规范
缩进
使用Tab缩进(4个空格)。
.element { |
分号
每个属性声明末尾都要加分号。
.element { |
空格
以下几种情况不需要空格:
- 属性名后;
- 多个规则的分隔符
,
前; - !important
!
后; - 属性值中
(
后和)
前; - 行末不要有多余的空格。
以下几种情况需要空格:
- 属性值前;
- 选择器
>
,+
,~
前后; {
前;- !important
!
前; - @else 前后;
- 属性值中的
,
后; - 注释
/*
后和*/
前。
/* 不推荐写法 */ |
空行
以下几种情况需要空行:
- 文件最后保留一个空行;
}
后最好跟一个空行,包括less中嵌套的规则;- 属性之间需要适当的空行,具体见属性声明顺序。
/* 不推荐写法 */ |
换行
以下几种情况不需要换行:
{
前。
以下几种情况需要换行:
{
后和}
前;- 每个属性独占一行;
- 多个规则的分隔符
,
后。
/* 不推荐写法 */ |
注释
- CSS注释统一用
/* */
; - LESS代码统一用
//
; - 缩进与下一行代码保持一致;
- 可位于一个代码行的末尾,与代码间隔一个空格。
// Modal header |
引号
- 最外层统一使用双引号;
- url的内容要用引号;
- 属性选择器中的属性值需要引号。
.element:after { |
命名
- 类名使用小写字母,以中划线分隔;
- id采用驼峰式命名;
- less中的变量、函数、混合采用驼峰式命名。
/* class */ |
属性声明顺序
相关的属性声明按右边的顺序做分组处理,组之间需要有一个空行。.declaration-order {
display: block;
float: right;
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
z-index: 100;
border: 1px solid #e5e5e5;
border-radius: 3px;
width: 100px;
height: 100px;
font: normal 13px "Helvetica Neue", sans-serif;
line-height: 1.5;
text-align: center;
color: #333;
background-color: #f5f5f5;
opacity: 1;
}
// 下面是推荐写法的属性的顺序 |
颜色
- 颜色16进制用小写字母;
- 颜色16进制尽量用简写。
/* 不推荐写法 */ |
属性简写
- 属性简写需要您非常清楚属性值的正确顺序,而且在大多数情况下并不需要设置属性简写中包含的所有值,所以建议尽量分开声明会更加清晰;
- margin和padding相反,需要使用简写;
常见的属性简写包括:
font
background
transition
animation
/* 不推荐写法 */ |
媒体查询
尽量将媒体查询的规则靠近与他们相关的规则,不要将他们一起放到一个独立的样式文件中,或者丢在文档的最底部,这样做只会让大家以后更容易忘记他们。
.element { |
LESS相关
声明顺序:
- @import;
- 变量声明;
- 自身属性;
- 嵌套规则。
@import "dialog.less"; |
杂项
- 不允许有空的规则;
- 元素选择器用小写字母;
- 去掉小数点前面的
0
; - 去掉数字中不必要的小数点和末尾的
0
; - 属性值
0
后面不要加单位; - 同个属性不同前缀的写法需要在垂直方向保持对齐,具体参照右边的写法;
- 无前缀的标准属性应该写在有前缀的属性后面;
- 不要在同个规则里出现重复的属性,如果重复的属性是连续的则没关系;
- 不要在一个文件里出现两个相同的规则;
- 用
border: 0
; 代替border: none
; - 选择器不要超过4层(在less中如果超过4层应该考虑用嵌套的方式来写);
- 发布的代码中不要有
@import
; - 尽量少用
*
选择器。
/* 不推荐写法 */ |
JavaScript编码规范
缩进
使用Tab缩进(4个空格)。
var x = 1, |
单行长度
不要超过80,但如果编辑器开启word wrap
可以不考虑单行长度。
分号
以下几种情况后需加分号:
- 变量声明;
- 表达式。
return
throw
break
continue
do-while
/* 声明 */ |
空格
以下几种情况不需要空格:
- 对象的属性名后;
- 前缀一元运算符后;
- 后缀一元运算符前;
- 函数调用括号前;
- 无论是函数声明还是函数表达式,
(
前不要空格; - 数组的
[
后和]
前; - 对象的’{‘后和’}’前;
- 运算符’(‘后和’)’前。
以下几种情况需要空格:
- 二元运算符前后;
- 三元运算符
?:
前后; - 代码块
{
前; - 下列关键字前:
else
,while
,catch
,finally
; - 下列关键字后:
if
,else
,for
,while
,do
,switch
,case
,try
,catch
,finally
,with
,return
,typeof
; - 单行注释
//
后(若单行注释和代码同行,则//
前也需要),多行注释*
后; - 对象的属性值前;
for
循环,分号后留有一个空格,前置条件如果有多个,逗号后留一个空格;- 无论是函数声明还是函数表达式,
{
前一定要有空格; - 函数的参数之间。
// 不推荐写法 |
空行
以下几种情况需要空行:
- 变量声明后(当变量声明在代码块的最后一行时,则无需空行);
- 注释前(当注释在代码块的第一行时,则无需空行);
- 代码块后(在函数调用、数组、对象中则无需空行);
- 文件最后保留一个空行。
// 在声明变量之后留一空行 |
换行
换行的地方,行末必须有’,’或者运算符;
以下几种情况不需要换行:
- 下列关键字后:
else
,catch
,finally
- 代码块’{‘前
以下几种情况需要换行:
- 代码块’{‘后和’}’前
- 变量赋值后
// 不推荐写法 |
单行注释
- 双斜线后,必须跟一个空格;
- 缩进与下一行代码保持一致;
- 可位于一个代码行的末尾,与代码间隔一个空格。
if (condition) { |
多行注释
最少三行, ‘*’后跟一个空格,具体参照右边的写法;
建议在以下情况下使用:
- 难于理解的代码段
- 可能存在错误的代码段
- 浏览器特殊的HACK代码
- 业务逻辑强相关的代码
/* |
文档注释
各类标签@param
, @method
等请参考 usejsdoc 和 JSDoc Guide;
建议在以下情况下使用:
- 所有常量
- 所有函数
- 所有类
/** |
引号
最外层统一使用单引号。
// 不推荐写法 |
变量命名
- 标准变量采用驼峰式命名(除了对象的属性外,主要是考虑到cgi返回的数据);
ID
在变量名中全大写;URL
在变量名中全大写;Android
在变量名中大写第一个字母;iOS
在变量名中小写第一个,大写后两个字母;- 常量全大写,用下划线连接;
- 构造函数,大写第一个字母;
- jquery对象必须以
$
开头命名。
var thisIsMyName; |
变量声明
一个函数作用域中所有的变量声明尽量提到函数首部,用一个var声明,不允许出现两个连续的var声明。
function doSomethingWithItems(items) { |
函数
无论是函数声明还是函数表达式,(
前不要空格,但{
前一定要有空格;
- 函数调用括号前不需要空格;
- 立即执行函数外必须包一层括号;
- 不要给
inline function
命名; - 参数之间用
,
分隔,注意逗号后有一个空格。
// 在'('之前不使用空格, 但在'{'之前要使用空格 |
数组、对象
- 对象属性名不需要加引号;
- 对象以缩进的形式书写,不要写在一行;
- 数组、对象最后不要有逗号。
// 不推荐写法 |
括号
下列关键字后必须有大括号(即使代码块的内容只有一行):if
, else
, for
, while
, do
, switch
, try
, catch
, finally
, with
。// 不推荐写法
if (condition)
doSomething();
// 推荐写法
if (condition) {
doSomething();
}
null
适用场景:
- 初始化一个将来可能被赋值为对象的变量
- 与已经初始化的变量做比较
- 作为一个参数为对象的函数的调用传参
- 作为一个返回对象的函数的返回值
不适用场景:
- 不要用null来判断函数调用时有无传参
- 不要与未初始化的变量做比较
// 不推荐写法 |
undefined
- 永远不要直接使用
undefined
进行变量判断; - 使用
typeof
和字符串undefined
对变量进行判断。
// 不推荐写法 |
jshint
- 用
===
,!==
代替==
,!=
; for-in
里一定要有hasOwnProperty
的判断;- 不要在内置对象的原型上添加方法,如
Array
,Date
; - 不要在内层作用域的代码里声明了变量,之后却访问到了外层作用域的同名变量;
- 变量不要先使用后声明;
- 不要在一句代码中单单使用构造函数,记得将其赋值给某个变量;
- 不要在同个作用域下声明同名变量;
- 不要在一些不需要的地方加括号,例:
delete(a.b)
; - 不要使用未声明的变量(全局变量需要加到
.jshintrc
文件的globals
属性里面); - 不要声明了变量却不使用;
- 不要在应该做比较的地方做赋值;
debugger
不要出现在提交的代码里;- 数组中不要存在空元素;
- 不要在循环内部声明函数;
- 不要像这样使用构造函数,例:
new function () { ... }, new Object;
。
// 不推荐写法 |
杂项
- 不要混用
tab
和space
; - 不要在一处使用多个
tab
或space
; - 换行符统一用
LF
; - 对上下文
this
的引用只能使用_this
,that
,self
其中一个来命名; - 行尾不要有空白字符;
switch
的falling through
和no default
的情况一定要有注释特别说明;- 不允许有空的代码块。
// 不推荐写法 |