代码规范之Web | zhiheng's blog

命名规则

上一篇总结了 java 代码规范，规则都来源于 google 的代码规范，这一篇总结 web 前端的规范。

项目命名：全部使用小写字母，用下划线隔开。例：my_project_name
目录命名：采用项目命名规则，有复数结构时，要采用复数命名法。例：styles，images，scripts
文件名：都采用小写字母，用下划线隔开加后缀。例：index_example.html，style_base.css，example_model.js。

HTML

语法：

缩进使用soft tab（4个空格）；
嵌套的节点应该缩进；
在属性上，使用双引号，不要使用单引号；
属性名全小写，用中划线做分隔符；
不要在自动闭合标签结尾处使用斜线（HTML5 规范指出他们是可选的）；
不要忽略可选的关闭标签，例：</li> 和 </body>。
虽然doctype不区分大小写，但是按照惯例，doctype大写关于html属性，大写还是小写
应在html标签上加上lang属性。这会给语音工具和翻译工具帮助，告诉它们应当怎么去发音和翻译。更多关于 lang 属性的说明在这里；而微软给出了一份更加详细的语言列表.aspx)，其中细分了zh-cn, zh-hk, zh-tw;
指定字符编码通常为’UTF-8’；
IE兼容模式：用标签可以指定页面应该用什么版本的IE来渲染；

<!DOCTYPE html>
<html lang="en-us">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
        <title>Page title</title>
        <!-- External CSS -->
        <link rel="stylesheet" href="code_guide.css">
        <!-- In-document CSS -->
		<style>
		    ...
		</style>
    </head>
    <body>
        <img src="images/company_logo.png" alt="Company">

        <h1 class="hello-world">Hello, world!</h1>

		<!-- External JS -->
		<script src="code_guide.js"></script>
		<!-- In-document JS -->
		<script>
		    ...
		</script>
    </body>
</html>

属性顺序
属性应该按照特定的顺序出现以保证易读性；

class
id
name
data-*
src, for, type, href, value , max-length, max, min, pattern
placeholder, title, alt
aria-*, role
required, readonly, disabled

class是为高可复用组件设计的，所以应处在第一位；
id更加具体且应该尽量少使用，所以将它放在第二位。

JS生成标签

在JS文件中生成标签让内容变得更难查找，更难编辑，性能更差。应该尽量避免这种情况的出现。

减少标签数量

在编写HTML代码时，需要尽量避免多余的父节点；
很多时候，需要通过迭代和重构来使HTML变得更少。

<!-- Not well -->
<span class="avatar">
    <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

CSS

缩进

使用soft tab（4个空格）。

.element {
    position: absolute;
    top: 10px;
    left: 10px;

    border-radius: 10px;
    width: 50px;
    height: 50px;
}

命名

类名使用小写字母，以中划线分隔
id采用驼峰式命名
scss中的变量、函数、混合、placeholder采用驼峰式命名

属性简写

属性简写需要你非常清楚属性值的正确顺序，而且在大多数情况下并不需要设置属性简写中包含的所有值，所以建议尽量分开声明会更加清晰；
margin 和 padding 相反，需要使用简写；
常见的属性简写包括：

font
background
transition
animation

/* not good */
.element {
    transition: opacity 1s linear 2s;
}

/* good */
.element {
    transition-delay: 2s;
    transition-timing-function: linear;
    transition-duration: 1s;
    transition-property: opacity;
}

颜色

颜色16进制用小写字母；
颜色16进制尽量用简写。

/* not good */
.element {
    color: #ABCDEF;
    background-color: #001122;
}

/* good */
.element {
    color: #abcdef;
    background-color: #012;
}

杂项

不允许有空的规则；

元素选择器用小写字母；

去掉小数点前面的0；

去掉数字中不必要的小数点和末尾的0；

属性值’0’后面不要加单位；

同个属性不同前缀的写法需要在垂直方向保持对齐，具体参照右边的写法；

无前缀的标准属性应该写在有前缀的属性后面；

不要在同个规则里出现重复的属性，如果重复的属性是连续的则没关系；

不要在一个文件里出现两个相同的规则；

用 border: 0; 代替 border: none;；

选择器不要超过4层（在scss中如果超过4层应该考虑用嵌套的方式来写）；

发布的代码中不要有 @import；

尽量少用’*’选择器。

JavaScript

缩进

使用soft tab（4个空格）。

var x = 1,
    y = 1;

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

分号

以下几种情况后需加分号：

变量声明
表达式
return
throw
break
continue
do-while

/* var declaration */
var x = 1;

/* expression statement */
x++;

/* do-while */
do {
    x++;
} while (x < 10);

引号

最外层统一使用单引号。

// not good
var x = "test";

// good
var y = 'foo',
    z = '<div id="test"></div>';

变量命名

标准变量采用驼峰式命名（除了对象的属性外，主要是考虑到cgi返回的数据）
‘ID’在变量名中全大写
‘URL’在变量名中全大写
‘Android’在变量名中大写第一个字母
‘iOS’在变量名中小写第一个，大写后两个字母
常量全大写，用下划线连接
构造函数，大写第一个字母
jquery对象必须以’$’开头命名

var thisIsMyName;
var goodID;
var reportURL;
var AndroidVersion;
var iOSVersion;
var MAX_COUNT = 10;
function Person(name) {
    this.name = name;
}
// not good
var body = $('body');

// good
var $body = $('body');

变量声明

一个函数作用域中所有的变量声明尽量提到函数首部，用一个var声明，不允许出现两个连续的var声明。

function doSomethingWithItems(items) {
    // use one var
    var value = 10,
        result = value + 10,
        i,
        len;

    for (i = 0, len = items.length; i < len; i++) {
        result += 10;
    }
}

函数

无论是函数声明还是函数表达式，’(‘前不要空格，但’{‘前一定要有空格；

函数调用括号前不需要空格；

立即执行函数外必须包一层括号；

不要给inline function命名；

参数之间用’, ‘分隔，注意逗号后有一个空格。

数组、对象

对象属性名不需要加引号；

对象以缩进的形式书写，不要写在一行；

数组、对象最后不要有逗号。

// not good
var a = {
    'b': 1
};

var a = {b: 1};

var a = {
    b: 1,
    c: 2,
};

// good
var a = {
    b: 1,
    c: 2
};

文档注释

各类标签@param, @method等请参考usejsdoc和JSDoc Guide；

建议在以下情况下使用：

所有常量
所有函数
所有类

/**
 * @func
 * @desc 一个带参数的函数
 * @param {string} a - 参数a
 * @param {number} b=1 - 参数b默认值为1
 * @param {string} c=1 - 参数c有两种支持的取值</br>1—表示x</br>2—表示xx
 * @param {object} d - 参数d为一个对象
 * @param {string} d.e - 参数d的e属性
 * @param {string} d.f - 参数d的f属性
 * @param {object[]} g - 参数g为一个对象数组
 * @param {string} g.h - 参数g数组中一项的h属性
 * @param {string} g.i - 参数g数组中一项的i属性
 * @param {string} [j] - 参数j是一个可选参数
 */
function foo(a, b, c, d, g, j) {
    ...
}

null

适用场景：

初始化一个将来可能被赋值为对象的变量
与已经初始化的变量做比较
作为一个参数为对象的函数的调用传参
作为一个返回对象的函数的返回值
不适用场景：
不要用null来判断函数调用时有无传参
不要与未初始化的变量做比较

// not good
function test(a, b) {
    if (b === null) {
        // not mean b is not supply
        ...
    }
}

var a;

if (a === null) {
    ...
}

// good
var a = null;

if (a === null) {
    ...
}

undefined

永远不要直接使用undefined进行变量判断；

使用typeof和字符串’undefined’对变量进行判断。

// not good
if (person === undefined) {
    ...
}

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

杂项

不要混用tab和space；

不要在一处使用多个tab或space；

换行符统一用’LF’；

对上下文this的引用只能使用’_this’, ‘that’, ‘self’其中一个来命名；

行尾不要有空白字符；

switch的falling through和no default的情况一定要有注释特别说明；

不允许有空的代码块。

// not good
var a   = 1;

function Person() {
    // not good
    var me = this;

    // good
    var _this = this;

    // good
    var that = this;

    // good
    var self = this;
}

// good
switch (condition) {
    case 1:
    case 2:
        ...
        break;
    case 3:
        ...
    // why fall through
    case 4
        ...
        break;
    // why no default
}

// not good with empty block
if (condition) {

}

更多文章请关注微信公众号： zhiheng博客