注释

最后更新于：2022-04-01 22:25:27

## 注释使用 JSDoc 我们使用[JSDoc](http://code.google.com/p/jsdoc-toolkit/)中的注释风格. 行内注释使用 // 变量的形式. 另外, 我们也遵循[C++ 代码注释风格](http://docs.kissyui.com/docs/html/styleguide/google/cppguide.xml#Comments). 这也就是说你需要: * 版权和著作权的信息, * 文件注释中应该写明该文件的基本信息(如, 这段代码的功能摘要, 如何使用, 与哪些东西相关), 来告诉那些不熟悉代码的读者. * 类, 函数, 变量和必要的注释, * 期望在哪些浏览器中执行, * 正确的大小写, 标点和拼写. 为了避免出现句子片段, 请以合适的大/小写单词开头, 并以合适的标点符号结束这个句子. 现在假设维护这段代码的是一位初学者. 这可能正好是这样的! 目前很多编译器可从 JSDoc 中提取类型信息, 来对代码进行验证, 删除和压缩. 因此, 你很有必要去熟悉正确完整的 JSDoc . ### 顶层/文件注释顶层注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西. 应该提供文件的大体内容, 它的作者, 依赖关系和兼容性信息. 如下: ``` // Copyright 2009 Google Inc. All Rights Reserved. /** * @fileoverview Description of file, its uses and information * about its dependencies. * @author user@google.com (Firstname Lastname) */ ``` ### 类注释每个类的定义都要附带一份注释, 描述类的功能和用法.也需要说明构造器参数. 如果该类继承自其它类, 应该使用 `@extends` 标记. 如果该类是对接口的实现, 应该使用 `@implements` 标记. ``` /** * Class making something fun and easy. * @param {string} arg1 An argument that makes this more interesting. * @param {Array.} arg2 List of numbers to be processed. * @constructor * @extends {goog.Disposable} */ project.MyClass = function(arg1, arg2) { // ... }; goog.inherits(project.MyClass, goog.Disposable); ``` ### 方法与函数的注释提供参数的说明. 使用完整的句子, 并用第三人称来书写方法说明. ``` /** * Converts text to some completely different text. * @param {string} arg1 An argument that makes this more interesting. * @return {string} Some return value. */ project.MyClass.prototype.someMethod = function(arg1) { // ... }; /** * Operates on an instance of MyClass and returns something. * @param {project.MyClass} obj Instance of MyClass which leads to a long * comment that needs to be wrapped to two lines. * @return {boolean} Whether something occured. */ function PR_someMethod(obj) { // ... } ``` 对于一些简单的, 不带参数的 getters, 说明可以忽略. ``` /** * @return {Element} The element for the component. */ goog.ui.Component.prototype.getElement = function() { return this.element_; }; ``` ### 属性注释也需要对属性进行注释. ``` /** * Maximum number of things per pane. * @type {number} */ project.MyClass.prototype.someProperty = 4; ``` ### 类型转换的注释有时, 类型检查不能很准确地推断出表达式的类型, 所以应该给它添加类型标记注释来明确之, 并且必须在表达式和类型标签外面包裹括号. ``` /** @type {number} */ (x) (/** @type {number} */ x) ``` ### JSDoc 缩进如果你在 `@param`, `@return`, `@supported`, `@this` 或 `@deprecated` 中断行, 需要像在代码中一样, 使用4个空格作为一个缩进层次. ``` /** * Illustrates line wrapping for long param/return descriptions. * @param {string} foo This is a param with a description too long to fit in * one line. * @return {number} This returns something that has a description too long to * fit in one line. */ project.MyClass.prototype.method = function(foo) { return 5; }; ``` 不要在 `@fileoverview` 标记中进行缩进. 虽然不建议, 但也可对说明文字进行适当的排版对齐. 不过, 这样带来一些负面影响, 就是当你每次修改变量名时, 都得重新排版说明文字以保持和变量名对齐. ``` /** * This is NOT the preferred indentation method. * @param {string} foo This is a param with a description too long to fit in * one line. * @return {number} This returns something that has a description too long to * fit in one line. */ project.MyClass.prototype.method = function(foo) { return 5; }; ``` ### 枚举 ``` /** * Enum for tri-state values. * @enum {number} */ project.TriState = { TRUE: 1, FALSE: -1, MAYBE: 0 }; ``` 注意一下, 枚举也具有有效[类型](#JavaScript_Types), 所以可以当成参数类型来用. ``` /** * Sets project state. * @param {project.TriState} state New project state. */ project.setState = function(state) { // ... }; ``` ### Typedefs 有时类型会很复杂. 比如下面的函数, 接收 Element 参数: ``` /** * @param {string} tagName * @param {(string|Element|Text|Array.|Array.)} contents * @return {Element} */ goog.createElement = function(tagName, contents) { ... }; ``` 你可以使用 `@typedef` 标记来定义个常用的类型表达式. ``` /** * @param {string} tagName * @param {goog.ElementContent} contents * @return {Element} */ goog.createElement = function(tagName, contents) { ... }; ``` ### JSDoc 标记表 #### `@param` 模板 & 例子： ``` @param {Type} 变量名描述 ``` _如:_ ``` /** * Queries a Baz for items. * @param {number} groupNum Subgroup id to query. * @param {string|number|null} term An itemName, * or itemId, or null to search everything. */ goog.Baz.prototype.query = function(groupNum, term) { // ... }; ``` 描述：给方法, 函数, 构造器中的参数添加说明. 类型检测支持：完全支持. #### `@return` 模板 & 例子： ``` @return {Type} 描述 ``` _如:_ ``` /** * @return {string} The hex ID of the last item. */ goog.Baz.prototype.getLastId = function() { // ... return id; }; ``` 描述：给方法, 函数的返回值添加说明. 在描述布尔型参数时, 用 “Whether the component is visible” 这种描述优于 “True if the component is visible, false otherwise”. 如果函数没有返回值, 就不需要添加`@return`标记. 类型检测支持：完全支持. #### `@author` 模板 & 例子： ``` @author username@google.com (first last) ``` _如:_ ``` /** * @fileoverview Utilities for handling textareas. * @author kuth@google.com (Uthur Pendragon) */ ``` 描述：表明文件的作者,通常仅会在`@fileoverview`注释中使用到它. 类型检测支持：不需要. #### `@see` 模板 & 例子： ``` @see Link ``` _如:_ ``` /** * Adds a single item, recklessly. * @see #addSafely * @see goog.Collect * @see goog.RecklessAdder#add ... ``` 描述：给出引用链接, 用于进一步查看函数/方法的相关细节. 类型检测支持：不需要. #### `@fileoverview` 模板 & 例子： ``` @fileoverview 描述 ``` _如:_ ``` /** * @fileoverview Utilities for doing things that require this very long * but not indented comment. * @author kuth@google.com (Uthur Pendragon) */ ``` 描述：文件通览. 类型检测支持：不需要. #### `@constructor` 模板 & 例子： ``` @constructor ``` _如:_ ``` /** * A rectangle. * @constructor */ function GM_Rect() { ... } ``` 描述：指明类中的构造器. 类型检测支持：会检查. 如果省略了, 编译器将禁止实例化. #### `@interface` 模板 & 例子： ``` @interface ``` _如:_ ``` /** * A shape. * @interface */ function Shape() {}; Shape.prototype.draw = function() {}; /** * A polygon. * @interface * @extends {Shape} */ function Polygon() {}; Polygon.prototype.getSides = function() {}; ``` 描述：指明这个函数是一个接口. 类型检测支持：会检查. 如果实例化一个接口, 编译器会警告. #### `@type` 模板 & 例子： ``` @type Type @type {Type} ``` _如:_ ``` /** * The message hex ID. * @type {string} */ var hexId = hexId; ``` 描述：标识变量, 属性或表达式的类型. 大多数类型是不需要加大括号的, 但为了保持一致, 建议统一加大括号. | 类型检测支持：会检查 #### `@extends` 模板 & 例子： ``` @extends Type @extends {Type} ``` _如:_ ``` /** * Immutable empty node list. * @constructor * @extends goog.ds.BasicNodeList */ goog.ds.EmptyNodeList = function() { ... }; ``` 描述：与 @constructor 一起使用, 用来表明该类是扩展自其它类的. 类型外的大括号可写可不写. 类型检测支持：会检查 #### `@implements` 模板 & 例子： ``` @implements Type @implements {Type} ``` _如:_ ``` /** * A shape. * @interface */ function Shape() {}; Shape.prototype.draw = function() {}; /** * @constructor * @implements {Shape} */ function Square() {}; Square.prototype.draw = function() { ... }; ``` 描述：与 @constructor 一起使用, 用来表明该类实现自一个接口. 类型外的大括号可写可不写. 类型检测支持：会检查. 如果接口不完整, 编译器会警告. #### `@lends` 模板 & 例子： ``` @lends objectName @lends {objectName} ``` _如:_ ``` goog.object.extend( Button.prototype, /** @lends {Button.prototype} */ { isButton: function() { return true; } }); ``` 描述：表示把对象的键看成是其他对象的属性. 该标记只能出现在对象语法中. 注意, 括号中的名称和其他标记中的类型名称不一样, 它是一个对象名, 以”借过来”的属性名命名. 如, @type {Foo} 表示 “Foo 的一个实例”, but @lends {Foo} 表示 “Foo 构造器”. 更多有关此标记的内容见[JSDoc Toolkit docs](http://code.google.com/p/jsdoc-toolkit/wiki/TagLends). 类型检测支持：会检查 #### `@private` 模板 & 例子： ``` @private ``` _如:_ ``` /** * Handlers that are listening to this logger. * @type Array. * @private */ this.handlers_ = []; ``` 描述：指明那些以下划线结尾的方法和属性是 [私有](#Visibility__private_and_protected_fields_)的. 不推荐使用后缀下划线, 而应改用 @private. 类型检测支持：需要指定标志来开启. #### `@protected` 模板 & 例子： ``` @protected ``` _如:_ ``` /** * Sets the component's root element to the given element. Considered * protected and final. * @param {Element} element Root element for the component. * @protected */ goog.ui.Component.prototype.setElementInternal = function(element) { // ... }; ``` 描述：指明接下来的方法和属性是[被保护](#Visibility__private_and_protected_fields_)的. 被保护的方法和属性的命名不需要以下划线结尾, 和普通变量名没区别. | 类型检测支持：需要指定标志来开启. #### `@this` 模板 & 例子： ``` @this Type @this {Type} ``` _如:_ ``` pinto.chat.RosterWidget.extern('getRosterElement', /** * Returns the roster widget element. * @this pinto.chat.RosterWidget * @return {Element} */ function() { return this.getWrappedComponent_().getElement(); }); ``` 描述：指明调用这个方法时, 需要在哪个上下文中. 当 this 指向的不是原型方法的函数时必须使用这个标记. 类型检测支持：会检查 #### `@supported` 模板 & 例子： ``` @supported 描述 ``` _如:_ ``` /** * @fileoverview Event Manager * Provides an abstracted interface to the * browsers' event systems. * @supported So far tested in IE6 and FF1.5 */ ``` 描述：在文件概述中用到, 表明支持哪些浏览器. 类型检测支持：不需要. #### `@enum` 模板 & 例子： ``` @enum {Type} ``` _如:_ ``` /** * Enum for tri-state values. * @enum {number} */ project.TriState = { TRUE: 1, FALSE: -1, MAYBE: 0 }; ``` 描述：用于枚举类型. 类型检测支持：完全支持. 如果省略, 会认为是整型. #### `@deprecated` 模板 & 例子： ``` @deprecated 描述 ``` _如:_ ``` /** * Determines whether a node is a field. * @return {boolean} True if the contents of * the element are editable, but the element * itself is not. * @deprecated Use isField(). */ BN_EditUtil.isTopEditableField = function(node) { // ... }; ``` 描述：告诉其他开发人员, 此方法, 函数已经过时, 不要再使用. 同时也会给出替代方法或函数. 类型检测支持：不需要 #### `@override` 模板 & 例子： ``` @override ``` _如:_ ``` /** * @return {string} Human-readable representation of project.SubClass. * @override */ project.SubClass.prototype.toString() { // ... }; ``` 描述：指明子类的方法和属性是故意隐藏了父类的方法和属性. 如果子类的方法和属性没有自己的文档, 就会继承父类的. 类型检测支持：会检查 #### `@inheritDoc` 模板 & 例子： ``` @inheritDoc ``` _如:_ ``` /** @inheritDoc */ project.SubClass.prototype.toString() { // ... }; ``` 描述：指明子类的方法和属性是故意隐藏了父类的方法和属性, 它们具有相同的文档. 注意: 使用@inheritDoc 意味着也同时使用了 @override. | 类型检测支持：会检查 #### `@code` 模板 & 例子： ``` {@code …} ``` _如:_ ``` /** * Moves to the next position in the selection. * Throws {@code goog.iter.StopIteration} when it * passes the end of the range. * @return {Node} The node at the next position. */ goog.dom.RangeIterator.prototype.next = function() { // ... }; ``` 描述：说明这是一段代码, 让它能在生成的文档中正确的格式化. 类型检测支持：不适用. #### `@license` or `@preserve` 模板 & 例子： ``` @license ``` 描述： _如:_ ``` /** * @preserve Copyright 2009 SomeThirdParty. * Here is the full license text and copyright * notice for this file. Note that the notice can span several * lines and is only terminated by the closing star and slash: */ ``` 描述：所有被标记为 @license 或 @preserve 的, 会被编译器保留不做任何修改而直接输出到最终文挡中. 这个标记让一些重要的信息(如法律许可或版权信息)原样保留, 同样, 文本中的换行也会被保留. | 类型检测支持：不需要. #### `@noalias` 模板 & 例子： ``` @noalias ``` _如:_ ``` /** @noalias */ function Range() {} ``` 描述：在外部文件中使用, 告诉编译器不要为这个变量或函数重命名. 类型检测支持：不需要. #### `@define` 模板 & 例子： ``` @define {Type} 描述 ``` _如:_ ``` /** @define {boolean} */ var TR_FLAGS_ENABLE_DEBUG = true; /** @define {boolean} */ goog.userAgent.ASSUME_IE = false; ``` 描述：表示该变量可在编译时被编译器重新赋值. 在上面例子中, BUILD 文件中指定了 ``` –define=’goog.userAgent.ASSUME_IE=true’ ``` 这个编译之后, 常量 goog.userAgent.ASSUME_IE 将被全部直接替换为 true. 类型检测支持：不需要. #### `@export` 模板 & 例子： ``` @export ``` _如:_ ``` /** @export */ foo.MyPublicClass.prototype.myPublicMethod = function() { // ... }; ``` 描述：上面的例子代码, 当编译器运行时指定 –generate_exports 标志, 会生成下面的代码: ``` goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', foo.MyPublicClass.prototype.myPublicMethod); ``` 编译后, 将源代码中的名字原样导出. 使用 @export 标记时, 应该 1. 包含 //javascript/closure/base.js, 或者 2. 在代码库中自定义 goog.exportSymbol 和 goog.exportProperty 两个方法, 并保证有相同的调用方式. 类型检测支持：不需要. #### `@const` 模板 & 例子： ``` @const ``` _如:_ ``` /** @const */ var MY_BEER = 'stout'; /** * My namespace's favorite kind of beer. * @const * @type {string} */ mynamespace.MY_BEER = 'stout'; /** @const */ MyClass.MY_BEER = 'stout'; ``` 描述：声明变量为只读, 直接写在一行上. 如果其他代码中重写该变量值, 编译器会警告. 常量应全部用大写字符, 不过使用这个标记, 可以帮你消除命名上依赖. 虽然 jsdoc.org 上列出的 @final 标记作用等价于 @const , 但不建议使用. @const 与 JS1.5 中的 const 关键字一致. 注意, 编译器不禁止修改常量对象的属性(这与 C++ 中的常量定义不一样). 如果可以准确推测出常量类型的话，那么类型申明可以忽略. 如果指定了类型, 应该也写在同一行上. 变量的额外注释可写可不写. 类型检测支持：支持. #### `@nosideeffects` 模板 & 例子： ``` @nosideeffects ``` _如:_ ``` /** @nosideeffects */ function noSideEffectsFn1() { // ... }; /** @nosideeffects */ var noSideEffectsFn2 = function() { // ... }; /** @nosideeffects */ a.prototype.noSideEffectsFn3 = function() { // ... }; ``` 描述：用于对函数或构造器声明, 说明调用此函数不会有副作用. 编译器遇到此标记时, 如果调用函数的返回值没有其他地方使用到, 则会将这个函数整个删除. 类型检测支持：不需要检查. #### `@typedef` 模板 & 例子： ``` @typedef ``` _如:_ ``` /** @typedef {(string|number)} */ goog.NumberLike; /** @param {goog.NumberLike} x A number or a string. */ goog.readNumber = function(x) { ... } ``` 描述：这个标记用于给一个复杂的类型取一个别名. 类型检测支持：会检查 #### `@externs` 模板 & 例子： ``` @externs ``` _如:_ ``` /** * @fileoverview This is an externs file. * @externs */ var document; ``` 描述：指明一个外部文件. 类型检测支持：不会检查在第三方代码中, 你还会见到其他一些 JSDoc 标记. 这些标记在[JSDoc Toolkit Tag Reference](http://code.google.com/p/jsdoc-toolkit/wiki/TagReference)都有介绍到, 但在 Google 的代码中, 目前不推荐使用. 你可以认为这些是将来会用到的 “保留” 名. 它们包含: * @augments * @argument * @borrows * @class * @constant * @constructs * @default * @event * @example * @field * @function * @ignore * @inner * @link * @memberOf * @name * @namespace * @property * @public * @requires * @returns * @since * @static * @version ### JSDoc 中的 HTML 类似于 JavaDoc, JSDoc 支持许多 HTML 标签, 如 `

`, ``, ``, ``, ``, ``, ``, 等等.

这就是说 JSDoc 不会完全依照纯文本中书写的格式. 所以, 不要在 JSDoc 中, 使用空白字符来做格式化:



```
/**
 * Computes weight based on three factors:
 *   items sent
 *   items received
 *   last timestamp
 */
```



上面的注释, 出来的结果是:

```
Computes weight based on three factors: items sent items received items received
```

应该这样写:



```
/**
 * Computes weight based on three factors:
 * 
 * items sent
 * 
items received
 * 
last timestamp
 * 
 */
```



另外, 也不要包含任何 HTML 或类 HTML 标签, 除非你就想让它们解析成 HTML 标签.



```
/**
 * Changes  tags to  tags.
 */
```



出来的结果是:

```
Changes tags to tags.
```

另外, 也应该在源代码文件中让其他人更可读, 所以不要过于使用 HTML 标签:



```
/**
 * Changes <b> tags to <span> tags.
 */
```



上面的代码中, 其他人就很难知道你想干嘛, 直接改成下面的样子就清楚多了:



```
/**
* Changes 'b' tags to 'span' tags.
*/
```











### 编译



推荐使用





建议您去使用 JS 编译器, 如 [Closure Compiler](http://code.google.com/closure/compiler/).









### Tips and Tricks



JavaScript 小技巧





True 和 False 布尔表达式

下面的布尔表达式都返回 false:

*   `null`
*   `undefined`
*   `''` 空字符串
*   `0` 数字0

但小心下面的, 可都返回 true:

*   `'0'` 字符串0
*   `[]` 空数组
*   `{}` 空对象

下面段比较糟糕的代码:



```
while (x != null) {
```



你可以直接写成下面的形式(只要你希望 x 不是 0 和空字符串, 和 false):







如果你想检查字符串是否为 null 或空:



```
if (y != null && y != '') {
```



但这样会更好:







注意: 还有很多需要注意的地方, 如:

*   `Boolean('0') == true`
    `'0' != true`
    
*   `0 != null`
    `0 == []`
    `0 == false`
    
*   `Boolean(null) == false`
    `null != true`
    `null != false`
    
*   `Boolean(undefined) == false`
    `undefined != true`
    `undefined != false`
    
*   `Boolean([]) == true`
    `[] != true`
    `[] == false`
    
*   `Boolean({}) == true`
    `{} != true`
    `{} != false`

### 条件(三元)操作符 (?:)

三元操作符用于替代下面的代码:



```
if (val != 0) {
  return foo();
} else {
  return bar();
}
```



你可以写成:







在生成 HTML 代码时也是很有用的:



```
var html = '';
```



### `&&` 和 `||`

二元布尔操作符是可短路的, 只有在必要时才会计算到最后一项.

“||” 被称作为 ‘default’ 操作符, 因为可以这样:



```
/** @param {*=} opt_win */
function foo(opt_win) {
  var win;
  if (opt_win) {
    win = opt_win;
  } else {
    win = window;
  }
  // ...
}
```



你可以使用它来简化上面的代码:



```
/** @param {*=} opt_win */
function foo(opt_win) {
  var win = opt_win || window;
  // ...
}
```



“&&” 也可简短代码.比如:



```
if (node) {
  if (node.kids) {
    if (node.kids[index]) {
      foo(node.kids[index]);
    }
  }
}
```



你可以像这样来使用:



```
if (node && node.kids && node.kids[index]) {
  foo(node.kids[index]);
}
```



或者:



```
var kid = node && node.kids && node.kids[index];
if (kid) {
  foo(kid);
}
```



不过这样就有点儿过头了:



```
node && node.kids && node.kids[index] && foo(node.kids[index]);
```



### 使用 join() 来创建字符串

通常是这样使用的:



```
function listHtml(items) {
  var html = '';
  for (var i = 0; i < items.length; ++i) {
    if (i > 0) {
      html += ', ';
    }
    html += itemHtml(items[i]);
  }
  html += '';
  return html;
}
```



但这样在 IE 下非常慢, 可以用下面的方式:



```
function listHtml(items) {
  var html = [];
  for (var i = 0; i < items.length; ++i) {
    html[i] = itemHtml(items[i]);
  }
  return '' + html.join(', ') + '';
}
```



你也可以是用数组作为字符串构造器, 然后通过 `myArray.join('')` 转换成字符串. 不过由于赋值操作快于数组的 `push()`, 所以尽量使用赋值操作.

### 遍历 Node List

Node lists 是通过给节点迭代器加一个过滤器来实现的.

这表示获取他的属性, 如 length 的时间复杂度为 O(n), 通过 length 来遍历整个列表需要 O(n^2).



```
var paragraphs = document.getElementsByTagName('p');
for (var i = 0; i < paragraphs.length; i++) {
  doSomething(paragraphs[i]);
}
```



这样做会更好:



```
var paragraphs = document.getElementsByTagName('p');
for (var i = 0, paragraph; paragraph = paragraphs[i]; i++) {
  doSomething(paragraph);
}
```



这种方法对所有的 collections 和数组(只要数组不包含 falsy 值) 都适用.

在上面的例子中, 也可以通过 firstChild 和 nextSibling 来遍历孩子节点.



```
var parentNode = document.getElementById('foo');
for (var child = parentNode.firstChild; child; child = child.nextSibling) {
  doSomething(child);
}
```

';