多行注释应当在代码需要更多文字去解释的时候使用。每个多行注释都至少有如下三行:
1.首行仅仅包括/*注释开始。该行不应当有其他文字。
2.接下来的行以*开头并保持左对齐。这些可以有文字描述。
3.最后一行以*/开头并同先前行保持对齐。也不应有其他文字。
多行注释的首行应当保持同它描述代码的相同层次的缩进。后续的每行应当有同样层次的缩进并附加一个空格(为了适当保持*字符的对齐)。每一个多行代码之前应当预留一个空行。
// 好的写法、 if (condition) { /* * 如果代码执行到这里 * 说明通过了所有的安全检测 */ allowed(); }
注释声明
注释有时候也可以用来给一段代码声明额外的信息。这些声明的格式以单个单词打头并紧跟一个冒号。可以使用的声明如下。
TODO:说明代码还未完成。应当包含下一步要做的事情。
HACK:表明代码实现走了一个捷径。应当包含为何使用hack的原因。这也可能表明该问题可能会有更好的解决办法。
XXX:说明代码是有问题的并应当尽快修复。
FIXME:说明代码是有问题的并应尽快修复。重要性略次于XXX。
REVIEW:说明代码在任何可能的改动都需要评审。
这些声明可能在一行或者多行注释中使用,并且应当遵循同一般注释类型相同的格式规则。
8.命名
变量和函数在命名时应当小心。命名应紧限于数字字母字符,某些情况下可以使用下划线(_)。最好不要在任何命名中使用美元符号($)或者反斜杠(\)。
变量命名应当采用驼峰命名格式,首字母小写,每个单词首字母大写。变量名的第一个单词应当是一个名词(而非动词)以避免同函数混淆。不要在变量名中使用下划线。
// 好的写法 var accountNumber = "test001"; // 不好的写法:大写字母开头 var AccountNumber = "test001"; // 不好的写法:动词开头 var getAccountNumber = "test001"; // 不好的写法:使用下划线 var account_number = "test001";
函数名也应当采用驼峰命名格式。函数名的第一个单词应当是动词(而非名词)来避免同变量混淆。函数名中最好不要使用下划线。
// 好的写法 function doSomething() { // code } // 不好的写法:大写字母开头 function DoSomething() { // code } // 不好的写法:名词开头 function something() { // 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 totalCount = 10; // 不好的写法:混合形式 var total_COUNT = 10;
对象的属性同变量的命名规则相同。对象的方法同函数的命名规则相同。如果属性或者方法是私有的,应当在之前加上一个下划线。
// 好的写法 var object = { _count: 10,4 _getCount: function() { return this._count; } }
9.变量与函数声明
变量声明