1. 简介
2. 快速参考
3. 命名规范
4. 特殊命名规范
5. 语法层次
6. 注释
7. JsDoc简介
1. 简介
Any violation to this guide is allowed if it enhances readability.
所有的代码都要变成可供他人容易阅读的。
—引用自Dojo Javascript 语法规范
2. 快速参考
1. 使用 Tab 键进行代码缩进，以节约代码大小(4个空格宽度)
2. 接口风格
|
结构 |
规则 |
样例 |
|
类 |
驼峰式 |
ModuleClass() |
|
公有方法 |
混合式 |
getPosition() |
|
公有变量 |
混合式 |
frameStyle |
|
常量 |
大写式 |
DEFAULT_FRAME_LAYOUT |
3. 其他风格
|
结构 |
规则 |
样例 |
|
私有方法 |
混合 |
_mixedCase |
|
私有变量 |
混合 |
_mixedCase |
|
方法（method）参数 |
混合 |
_mixedCase, mixedCase |
|
本地（local）变量 |
混合 |
_mixedCase, mixedCase |
4. 所有语句结束后，必须使用 ; 号结束
3.命名规范
1. 所有变量必须是有意义的英文，严厉禁止拼音
2. 变量允许使用公认英文缩写
3. 类命名必须是驼峰式
4. 常量必须所有单词大写，并且每个单词间加下划线
5. 枚举类型时，枚举的命名必须有意义，枚举与枚举成员必须以驼峰式
6. 常量和枚举必须在最前端定义，merge 时注意，必须把常量与枚举定义的文件放在文件列表的第一位
7. 变量内的简写单词不能全大写
XmlDocument strHtml
8. 函数开头必须是有意义的动词或动词短语
9. 私有类的变量属性成员 建议 使用混合式命名，并前面下下划线
10. 临时的全局变量放到一个全局的哈希表里，方便变量回收
11. 所有全局变量必须初始化
12. 大括号前面不能有换行符
13. 保留字以及特有的dom属性不能作为变量名
4.特殊命名规范
1. 前面加 “is” 的变量名应该为布尔值，亦可使用 “can” “has” “should”
2. 前面加 ”str” 的变量名应该为字符串
3. 前面加 “arr” 的变量名应该为数组
4. 前面加 “num” 或 “count” 的变量名应该为数字
5. “o” 作为局部变量或参数，表示为Object
6. “e” 作为局部变量或参数，表示为Element
7. 重复变量建议使用 ”i”, ”j”, ”k” （依次类推）等名称的变量
8. 能缩写的单词尽量缩写
9. 避免产生令人误解的布尔值
isNotNumber isNan
10. 处理错误的变量，必须在后面跟着 “Error”
11. 初始化用的函数 必须使用 “init” 开头，如果一个页面只有初始化可以单独使用 init()
12. 尽量做有意义的代码折行，不要让一行代码过长。(HTML 字符串除外)
13. 操作符 建议 使用空格隔开
14. 函数调用和方法 避免 使用空白
逗号（,） 建议 使用空白隔开。
5.语法层次
1. 普通代码段 应该 看起来如下：
while (!isDone){
doSomething();
isDone = moreToDo();
}
2. IF 语句 应该 看起来像这样：
if (someCondition){
statements;
} else if (someOtherCondition){
statements;
} else {
statements;
}
3. FOR 语句 应该 看起来像这样：
for (initialization; condition; update){
statements;
}
4. WHILE 语句 应该 看起来像这样：
while (!isDone) {
doSomething();
isDone = moreToDo();
}
5. DO … WHILE 语句 应该 看起来像这样：
do {
statements;
} while (condition);
6. SWITCH 语句 应该 看起来像这样：
switch (condition) {
case ABC:
statements;
// fallthrough
case DEF:
statements;
break;
default:
statements;
break;
}
7. TRY … CATCH 语句 应该 看起来像这样：
try {
statements;
} catch(ex) {
statements;
} finally {
statements;
}
8. 单行的 IF - ELSE，WHILE 或者 FOR 语句也 必须 加入括号：
if (condition) {
statement;
}
while (condition) {
statement;
}
6.注释
1. 一些你不打算给其他人使用的函数，建议添加 @ignore 让文档输出时可以忽略这段注释
2. 一些相关的功能相关的函数，建议加上@see Function 来对上下文做索引
3. 对于一些函数不建议或则需要注意的使用方法，必须加上 @deprecated 作为提醒
4. 每个js文件的文件头都必须包含 @fileoverview @author, 建议加上@version
5. 每个函数都必须使用JsDoc 来注释他的用意
6. 每个带参数的函数必须包含 @param
7. 每个有返回值的函数必须包含 @return
8. 构造函数 必须加上 @constructor
9. 继承函数 建议加上 @base 表示其继承于哪个类
10. 常用全局变量建议使用 JsDoc 的注释方式
11. 一般的变量及局部变量 才用 // 方式进行注释，建议在需要做注释的语句的上一行
12. 其他详情请参考 JsDoc 注释方法
7. JsDoc简介(Javascript Documentation Tool)
Java 语言引入了一个工具，名为javadoc。这个工具能够根据源代码中的文档注释以HTML格式生成API文档。所生成的HTML文档在任何Web 浏览器 上都能阅读，而且由于它是以HTML格式生成的，所以能够在线发布，这样开发人员就能很轻易地访问这些文档。以一种能够轻松浏览的格式来提供API 文 档，这种方法使得开发人员不必仔细地检查源代码才能理解某个类或方法会有怎样的行为，以及该如何使用。而JSDoc是面向JavaScript的一个类似 的工具（jsdoc.sourceforge.net）.
一个简单的JsDoc风格注释:
/**
* This is a subclass of Shape
* @constructor
* @base Shape
*/
function Circle(){
// …
}
JsDoc生成的html文档:
JSDoc注释使用
JSDoc 通过JS文件中的一些特殊JSDoc标记，解析文档。下面列出了可以创建HTML文档的一些特殊 JSDoc标记。( 如果你曾在Java代码中编写过 javadoc注释，应该对这些标记并不陌生)如果要在最后生成的文档中包含某个注释块，所有这些注释块都必须以/**开头，并以*/结束。
部分JSDoc 命令属性
|
命令名 |
描述 |
|
@param |
|
|
@argument |
指定参数名和说明来描述一个函数参数。 |
|
@return |
|
|
@returns |
描述函数的返回值。 |
|
@author |
指示代码的作者。 |
|
@deprecated |
指示一个函数已经废弃，不建议使用，而且在将来版本的代码中可能会彻底删除。要避免使用这段代码。 |
|
@see |
创建一个HTML链接指向指定类的描述。 |
|
@version |
指定发布版本。 |
|
@requires |
创建一个HTML链接，指向这个类所需的指定类。 |
|
@throws |
|
|
@exception |
描述函数可能抛出的异常的类型。 |
|
{@link} |
创建一个HTML链接，指向指定的类。这与@see很类似，但{@link}能嵌在注释文本中。 |
|
@fileoverview |
这是一个特殊的标记，如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提供文件的一个概述。 |
|
@class |
提供类的有关信息，用在构造函数的文档中。 |
|
@constructor |
明确一个函数是某个类的构造函数。 |
|
@type |
指定函数的返回类型。 |
|
@extends |
指示一个类派生了另一个类。通常JSDoc自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记。 |
|
@private |
指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了—private命令行选项。 |
|
@final
|
指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量。
|
|
@ignore |
JSDoc 会忽略有这个标记的函数。 |