《编写可维护的JavaScript》笔记 - 编程风格

第一部分  编程风格

 

第1章  基本的格式化

 

1.1  缩进层级

统一缩进层级。

主张两种缩进层级

• 使用制表符进行缩进
• 使用2/4/8个空格缩进

推荐使用4个空格字符作为一个缩进层级

//不好的示例

//好的示例

 

1.2  语句结尾

推荐总是以“；”结尾，如果省略了分号，JSLint和JSHint默认都会有警告。

 

1.3  行的长度

推荐将行长度限定在80个字符

 

1.4  换行

当一行长度达到了80个字符时，需要手动将一行拆成两行。通常会在运算符后换行，下一行会增加两个层级的缩进。

在下面这段代码中，if条件语句被拆成了两行，断行在&&运算符之后。if语句的主体部分依然是一个缩进，这样更容易阅读。

当给变量赋值时，第二行的位置应当和赋值运算符的位置保持对齐。

 

1.5  空行

建议在以下场景中添加空行：

• 在每个流程控制语句之前（if和for语句）
• 在方法之间
• 在方法中的局部变量和第一条语句之间
• 在单行/对行注释之前
• 在方法内的逻辑片段之间

 

1.6  命名

• 采用驼峰式命名法
• 变量使用名词开头
• 函数使用动词开头
• 单个字母（i、j、k）用于循环
• 常量使用大写字母和下划线命名（如MAX_COUNT）
• 构造函数使用大驼峰命名法（如Person）
• 命名长度尽可能短且抓住要点，避免没有意义的命名

以下是函数命名使用动词开头常见的约定

 

1.7  直接量

字符串：

• 字符串通篇使用单引号（双引号）包裹，避免穿插使用单引号和双引号
• 多行字符串使用字符串拼接符（+）将字符串分成多份

数字：

• 不要省略小数点之前或之后的数字
• 最好在代码中禁止使用八进制直接量

null:

最好的方式是将它当做对象的占位符。在下列场景中使用null:

• 用来初始化一个变量，这个变量可能被赋值为一个对象
• 用来和一个已经初始化的变量比较，这个变量可以是也可以不是一个对象
• 当函数的参数期望是对象时，用作参数传入
• 当函数的返回值期望是对象时，用作返回值传出

在下列场景中不应当使用null:

• 不要使用null来检测是否传入某个参数
• 不要用null来检测一个为初始化的变量

undefined：

每一个没有被初始化的变量都有一个初始值，即undefined。

应尽量避免或禁止在代码中使用undefined，这个值常常和返回“undefined”的typeof运算符混淆。

如果使用了一个可能（或可能不会）赋值为对象的变量时，则将其赋值为null

对象直接量：

数组直接量：

 

 

第2章  注释

 

2.1  单行注释

单行注释有三种使用方法：

• 独占一行的注释，用来解释下一行代码。这行注释之前总是有一个空行，且缩进层级与下一行代码保持一致
• 在代码行的尾部的注释，代码结束到注释之间至少有一个缩进。注释（包括之前的代码部分）不应当超过单行最大字数限制（80），如果超过了，就将这条注释放置于当前代码行的上方
• 被注释掉的大段代码（很多编辑器都可以批量注释多行代码）

 

2.2  多行注释

多行注释可以包裹跨行文本，以下这些都是合法的注释

但更推荐下面这种写法

以下是建议遵循的多行注释规范：

• 在注释会左侧加上星号*
• 总是出现在将要描述的代码段之前，注释和代码之间没有空行间隔
• 多行注释前应当有一个空格
• 缩进层级与其描述的代码保持一致

 

2.3  使用注释

添加注释的一般原则是

• 在需要让代码变得更清晰时添加注释
• 在难以理解的代码前添加注释
• 在可能被误认为错误的代码前添加注释
• 浏览器特性hack

在难以理解的代码前添加注释

在可能被误认为错误的代码前添加注释

浏览器特性hack

 

2.4  文档注释

推荐使用文档生产工具来为你的javascript生成文档。

推荐使用javaDoc文档格式：

• 多行注释以单斜线和双星号（/**）开始
• 描述信息使用@符号来表示一个或多个属性

当使用文档注释时，确保对如下内容添加注释：

• 所有的方法：应当对方法、期望的参数和可能的返回值添加注释描述
• 所有的构造函数：应当对自定义类型和期望的参数添加注释描述
• 所有包含文档化方法的对象：如果一个对象包含一个或多个附带文档注释的方法，那么这个对象也应当适当针对文档生产工具添加文档注释

 

 

第三章  语句和表达式

 

推荐不论块语句包含多行代码还是单行代码，都应当总是使用花括号。默认情况下，省略花括号在JSLint和JSHint中都会报警告。

所有的块语句都应到使用花括号，包括：

• if
• for
• while
• do...while...
• try...catch...finally

 

3.1  花括号的对齐方式

推荐以下这种风格，继承自JAVA

以下这种风格不推荐，Google JavaScript 风格指南明确禁止以下这种风格。

 

3.2  块语句间隔

推荐以下这种风格，在左圆括号之前和右括号之后各添加一个空格

以下两种风格也可以，但更推荐上边的风格

括号前后不加空格

括号外部前后，内部前后都加空格

 

3.3  switch 语句

• 每条case语句相对于switch关键字都缩进一个层级
• 从第二条case语句开始，每条case语句前后各有一个空行
• 只要是有意为之并且添加了注释，就可以使用case语句的连续执行
• 在没有默认行为且写了注释的情况下省略default

Douglas Crockford提出所有的case都应当以break、return或throw做结尾，禁止switch语句中出现连续执行，不小心省略case末尾的结束语句会容易引发bug.

 

3.4  with语句

强烈推荐避免使用with语句。

在严格模式下，with语句是被明确禁止的，如果使用则报语法错误。

 

3.5  for循环

• 使用break退出循环
• 使用条件判断语句代替continue

当使用了continue时，JSLint会给出警告，而JSHint不会给出警告

 

3.6  for-in循环

for-in循环不仅遍历对象的实例属性，同样还遍历从原型继承的属性

• 推荐总是在for-in循环中使用hasOwnProperty()
• 不要用for-in来遍历数组

 

第四章  变量、函数和运算符

 

4.1  变量声明

js变量声明语句都会被提前

下面这段代码

会被解析成

所以，在函数内部任意地方定义变量和在函数顶部定义变量是完一样的，总是建议：

• 将局部变量的定义作为函数内第一条语句
• 将所有var语句合并为一个语句，每个变量的初始赋值独占一行
• 没有初始值的变量放在var语句的末尾

 

4.2  函数声明

函数声明会被js引擎提前。

下面这段代码

会被解析成

推荐：

• 总是先声明函数，后使用
• 函数内部的局部函数应当紧接着变量声明之后声明
• 函数声明不应当出现在语句块之内

 

4.3  函数调用间隔

推荐在函数名和左括号之间没有空格，以区分块语句

 

4.4  立即调用的函数

推荐以下写法，添加一个圆括号。这样做并不会改变代码的逻辑，如果省略圆括号JSLint会报警告

 

4.5  严格模式

• 不推荐将“use strict”用在全局作用域中
• 多个函数应用严格模式可用立即执行函数

 

4.6  相等

• 推荐不要使用==和!=，而是使用===和!==
• 不在万不得已的情况下，不使用eval()， Function构造函数，setTimeout，setInterval执行js字符串

尽量不要使用以下方法执行js字符串代码