JavaScript编写风格指南 (二)

七：注释

// 频繁的使用注释有助于他人理解你的代码
// 1.代码晦涩难懂
// 2.可能被误认为是错误的代码
// 3.必要但不明显的针对特定浏览器的代码
// 4.对于对象，方法或者属性，生成文档是有必要的（使用恰当的文档注释）

七(一)：单行注释

// 单行注释应当用来说明一行代码或者一组相关的代码。单行注释可能有三种使用方式
// 1.独占一行的注释，用来解释下一行的代码
// 2.在代码行的尾部的注释，用来解释它之前的代码
// 3.多行，用来注释掉一个代码块

Example:

//好的写法
if (condition) {

//如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

//不好的写法:注释之前没有空行
if () {
    //如果代码执行到这里，则表明通过了所有安全性检查
    allowed();

//不好的写法:错误的缩进
if () {
    
//如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

//好的写法
var result = something +somethingElse; //注释

//不好的写法:代码和注释间没有足有的空格
var result = something +somethingElse;//注释

// 注释一个代码块时在连续多行使用单行注释是唯一可以接受的情况
// 多行注释不应当在这种情况下使用

//好的写法
// if (condition) {
//       doSomething();
//       theDoSomethingElse();
// }

七(二)：多行注释

多行注释应当在代码需要更多文字去解释的时候使用，每个多行注释都至少有如下三行。
1.首行仅仅包括/*注释开始.该行不应当有其他文字
2.接下来的行*开头并保持左对齐。这些行可以与文字描述
3.最后一行以*/开头并同先前保持对齐。也不应当有其它文字

// 多行注释的首行保持同它描述代码的相同层次的缩进，后续的每行应当有同样
// 层次的缩进并附加一个空格。每一个多行代码之前应当预留一个空行

//好的写法
if (condition) {

/*
    * 如果代码执行到这里
    * 说明通过了所有的安全性检测
    */
    allowed();
}

//不好的写法：注释之前无空行
if (condition) {
    /*
    * 如果代码执行到这里
    * 说明通过了所有的安全性检测
    */
    allowed();
}

七(三)：多行声明

// 注释有时候也可以用来给一段代码声明额外的信息。这些声明的格式以单个单词
// 打头并紧跟一个冒号。可使用的声明如下：

// TODO: 说明代码还未完成，应当包含下一步要做的事情
// HACK：表明代码实现走了一个捷径。应当包含为何使用 hack 的原因。
//       这也可能表明该问题可能会有更好的解决方法
// ××× : 说明代码是有问题的并应当尽快修复
// FIXME：说明代码是有问题的并应尽快修复。重要性略次与×××
// REVIEW: 说明代码任何可能的改动都需要评审

// 这些声明可能在一行或多行注释中使用，并且应当遵循同一般注释类型相同的格式规则

Example：

//好的写法
//TODO: 我希望找到以后总更快的方式
doSomething();

//好的写法
/*
* HACK: 不得不针对IE做的特殊处理。我计划后续有时间
* 重写这部分。这些代码可能需要在 1.72版本之前替换掉。
*/
if (document.all) {
    doSomething();
}

七(四)：多行声明

// 所有的变量在使用前都应当事先定义。变量定义应当放在函数开头，还有一个var
// 表达式，每行一个变量，除了首行。所有行都应当多一层缩进以使变量名能够垂直
// 方向对齐。变量定义是应当初始化，并且赋值操作操作符保持一致的缩进。初始化
// 的变量应当在未初始化变量之前

//好的写法
var count = 10,
    name = "M",
    found = false,
    empty;

//不好的写法:错误的缩进
var count= 10，
  name = "M",
  found = false,
  empty;

//不好的写法:未初始化的变量放在最前边
var empty，
    count = 10,
    name = "M",
    found = false,

七(五)：函数声明

// 函数应在使用前提前定义。一个不是作为方法的函数（也就是说没有作为一个对
// 象的属性）应当使用函数定义的格式（不是函数表达式和Function构造器格式）
// 函数名和开始圆括号之间不应当有空格。结束的圆括号和右边的花括号之间应该留意
// 个空格。右侧的花括号应当同function关键字保持同一行。开始和结束括号之间不应
// 该有空格。参数之间应当在逗号之后保留一个空格。函数体应当保持一级缩进。

//好的写法
function doSomething(arg1, arg2) {
    return arg1 + arg2;
}

//不好的写法：第一行不恰当的空格
function doSomething (arg1, arg2) {
    return arg1 + arg2;
}

//不好的写法：函数表达式
var doSomething = function(arg1, arg2) {
    return arg1 + arg2;
}

其它函数内部定义的函数应当在var语句后立即定义

//好的写法
function outer() {
    var count = 10,
        name = "M",
        found = false,
        empty;

function inner() {
        //代码
    }
}

//不好的写法
function outer() {

function inner() {
        //代码
    }

var count = 10,
        name = "M",
        found = false,
        empty;
}

// 匿名函数可能作为方法赋值给对象，或者作为其他函数的参数。function 关键字
// 同开始括号之间不应该有空格

//好的写法
object.method = function() {
    //code
};

//不好的写法
object.method = function () {
    //code
};

// 立即被调用的函数应当在函数调用的外层用圆括号包裹
//好的写法
var value = (function() {

//函数体

return {
        message: "Hi"
    }
}());

//不好的写法:圆括号位置不当
var value = (function() {

//函数体

return {
        message: "Hi"
    }
})();

七(六)：命名

// 变量和函数在命名时应当小心。命名应仅限制与数组字母字符，某些情况下也可以使用
// 下划线。最好不要在任何命名中使用美元符号（$）或者反斜杠（\）

// 变量命名也应当采用驼峰命名格式，首字母小写，每个单词字母大写。变量名的第
// 一个单词应当是一个名词（而非动词）以避免同函数混淆。不要在变量命名中使用下划线

//好的写法
var accountNumber = "23454";

//不好的写法:大写字母开头
var AccountNumber = "23454";

//不好的写法:动词开头
var getAccountNumber = "23454";

//不好的写法:使用下滑线
var account_number = "23454";

// 函数命名也应当采用驼峰命名格式。函数名的第一个单词应当是动词（而非名词）
// 来避免同变量混淆。函数名中最好不要使用下划线

//好的写法
function doSomething() {
    //code
}

//不好的写法:大写字母开头
function DoSomething() {
    //code
}

//不好的写法:使用下划线
function Do_Something() {
    //code
}

// 构造函数---通过new运算符创建新对象的函数---也应当以驼峰格式，命名并且
// 首字母大写，构造函数名称应当以非动词开头，因为new代表着创建一个对象实例的操作

//好的写法
function MyObject() {
    //code
}

//不好的写法：小写字母开头
function myObject() {
    //code
}

//不好的写法：使用下划线
function My_Object() {
    //code
}

//不好的写法: 使用动词开头
function getMyObject() {
    //code
}

// 常量（值不会被改变的变量）的命名应当是所有字母大写，不同单词之间用单个下滑下隔开

//好的写法
var TOTAL_COUNT = 10;

// 对象的属性同变量的命名规则相同。对象的方法同函数的命名规则相同。如果属性
// 或者方法是私有的，应当在之前加一个下划线

//好的写法
var object = {
    _count: 10,

_getCount:function () {
        return this._count;
    }
};