JS代码规范说明

JS即拿即用

编码格式

Javascript脚本文件编码格式统一使用UTF-8，使用Tab缩进，并且设置一个Tab符等于4个空格符。

引用

• CSS文件头部(head)导入，分框架样式文件和活动页面样式文件(TV和我爱斗地主的活动无样式框架)；
• JS文件通过document.write写入(并行)，并放置页面底部；
• 框架、库文件等定型文件或大文件直接导入(缓存)，特定活动文件推荐添加时间戳后缀或特定名称后缀，以防后续修改。

命名

1. 基本命名约束

• 驼峰式命名，适用于一切变量(包括JQ对象)、函数名，如：variableNamesLikeThis，addData。
• 常量全部字母大写，如： COPYRIGHT，PI 。
• jQuery对象变量名称使用 $开头，后接驼峰式名称，如：$coin；
• 函数名称命名建议采用：动词+名词(fGetData)、形容词+名词(fMainAnim)，意思明了，一目了然。
• • 具体的名称可采用(非强制推荐)匈牙利命名法： 变量名＝类型＋对象描述，见下表(简化版)：

===匈牙利命名法简化表格===

2. 文件命名

• 单个活动页面资源所在的文件夹名称与tpl.php页面名称一致，并推荐使用全小写。
• 老活动需要改动逻辑，需新建页面模板，新页面命名遵循：原活动名称+日期简写(football140320.tpl.php)。
• 新图片替换老图片资源的命名规则：若是一系列(award1,award2....)，可使用后续序列号以此推进；若是单张图片，可在将原图片备份基础上使用新图片替代，并按需添加图片名称后缀。
• 随着多平台和新活动的增多，为方便调整和适配，统一规定：icon名称为icon_appid.jpg/png；css名称actName+appid+theme.css；common.js名称actName+lang.js；包含文字或单个版本特有的背景图片，统一为picName+appid.jpg/png，方便统一管理；任何文字统一后端传入，尽量杜绝在页面中写入任何文字。
• 不同语言版本公用同一文件夹内资源，活动icon放入图标文件夹同一管理。

声明

1. 变量

• 除特殊情况，每个变量声明都要加上var关键字，严格控制作用域。
• 在同一个函数内部，局部变量的声明建议置于顶端。
• 申明的变量若值相同，建议不要采用连等写法。

在Javascript中，变量声明无论放在什么位置，都会被解析器置顶解析。另外置顶声明，一方面有利于代码管理，二来可减少重复声明变量引起不必要的问题。

function createPerson() {
    //正确
    var name = 'A';
    var age = 20;
    console.log(str); //undefined
    if(age > 18) {
        //不推荐的写法，应在函数体内顶部声明！
        var str = 'You are adult already!';
        console.log(str);
    }
}

2. 函数

• 嵌套函数可使用，一来可以防止一些方法暴露在外部，二来可以重用而减少代码量;但要预防闭包带来的隐患。
• 不推荐使用块内函数写法，JS没有块内作用域，不同浏览器解析也会有差异。

虽然大多数JS引擎都支持块内声明函数，但它并不是 ECMAScript 标准的一部分（详见 ECMA-262, 第13条和第14条）。更糟糕的是各引擎对于块内函数声明的实现都不一样，和 EcmaScript 的建议相违背。

if(x) {
    //不推荐的写法
    function test() {
        //code
    }
}

语句

1. 分号

'''每一语句或函数表达式都要加上分号，且每一条语句要换行，变量声明除外。'''

如果不加分号JS解释器也会按隐式分隔的标准去执行，但那样调试、压缩、合并的时候容易造成很多不必要的问题。

var method = function() {
    return 5;
}
(function() {
    // 一个匿名函数，在这里会被错误解析当作参数调用导致报错
})();
//这段程序执行时，浏览器会报错误提示："TypeError: number is not a function"

2. 大括号

• 推荐使用大括号跟在起首句的后面。
• 条件判断语句也最好添加{}，即便只有一条执行语句。

//不推荐
function method() 
{
    //code
}
//推荐的写法
function method() {
    //code...
}
if (a) b(); c();
//原意可能是:
if (a) {
    b();
    c();
}
//实际就会变成
if (a) {
    b();
}
c();

3. 字符串

单引号（'）比双引号（"）更好。

使用单引号（'）比双引号（"）更好，特别是当创建一个HTML代码的字符串时候：

var msg = '<div class="text">This is some HTML</div>';

JSON对象

规范定义JSON对象，需补全双引号，它可以避免在编码过程中出现不必须要的错误。

var data = {
    name: 'json' //不推荐的写法
};
var data2 = {
    "name": 'json' //推荐写法
};

注释

1. 类的注释

对功能和类型的描述，还有一些参数和原型描述等信息。

/**
 * 圆类.
 * @param {Number} x 圆的x轴坐标.
 * @param {Number} y 圆的y轴坐标.
 * @param {Number} r 圆的半径.
 * @constructor
 */
function Circle(x, y, r) {
    this.x = x;
    this.y = y;
    this.r = r;
}

2. 方法/函数的注释

应有参数和返回值的描述，且方法描述要以使用者的身份去写。

/**
 * 获取圆的面积
 * @return {Number} 圆面积的值
 */
function getArea() {
    return this.r * 2 * 3.14;
}

3. 属性、变量和常量的描述

/**
 * 圆周率常量
 * @type {Number}
 * @const
 */
var PI = Math.PI;
function Circle(x, y, r) {
    /* 圆的x轴坐标 */
    this.x = x;
    /* 圆的y轴坐标 */
    this.y = y;
    /* 圆的半径 */
    this.r = r;
}