编写可维护的JavaScript-第二章(注释)笔记

发表于 更新于

单行注释

单行注释以两个斜线开始,以行尾结束.单行注释有三种使用方法:

  1. 独占一行的注释,用来解释下一行代码。这行注释之前总有一个空行,且缩进层级和下一行代码保持一致.
  2. 在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释(包括之前的代码部分)不应该超过单行最大字符数限制,如果超过了,就将这条注释放置于当前代码行的上方。
  3. 被注释的打断代码

多行注释

多行注释可以包裹跨行文本。

使用注释

添加注释的一般原则是,在需要让代码变得更清晰时添加注释。

1
2
3
4
5
6
7
8
9
10

// 不好的写法

// 初始化 count
var count = 10;

// 好的写法

// 改变这个值可能会让它变成青蛙
var count = 10;

使用注释的场景

  1. 难于理解的代码通常都应当加注释。
  2. 当代码看上去有错误的时应当加注释。
  3. 应当对方法、期望的从桉树和可能的返回值添加注释描述。
  4. 应当对自定义类型和期望的参数添加注释描述。
  5. 应当对包含文档花方法的对象添加注释描述。