Js/javascript Code Comment Specifications and examples

Note In the code writing process of importance, write code more than half a year can be deeply realized. Code that is not annotated is not a good code. For others to learn, at the same time for their own later to the code "upgrade" to see the Js/javascript Code annotation specifications and examples. From: http://www.56.com/style/-doc-/v1/tpl/js_dev_spec/spec-comment.html

file Comments

The file comments are located at the very front of the file and should include the following information about the file: Description and version (required) The project address (must) the copyright notice (must) the open source Agreement (required) version number (must) modification time (must), in ISO format (can use sublime Text Insertdate plug-in insert) file comments must all be in English characters and exist in the development and production versions of the file. For example:

1 2345

/*!   * jraiser 2 Javascript Library   * waterfall-v1.0.0 (2013-03-15t14:55:51+0800)   * http://jraiser.org/| Released under MIT license   */

1234	/*! * kan.56.com - v1.1 (2013-03-08T15:30:32+0800) * Copyright 2005-2013 56.com */

If some open source components are included in the file, they must be described in the file comments. For example:

1234567

/*! * jRaiser 2 Javascript Library * sizzle - v1.9.1 (2013-03-15T10:07:24+0800) * http://jraiser.org/ | Released under MIT license * * Include sizzle (http://sizzlejs.com/) */

General notes

General comments are intended to help developers and readers understand the program better and do not appear in the API documentation. Where the single-line comment begins with "//"; The multiline comment begins with "/*" and ends with "*/". The use of general notes is subject to the following provisions.

• Always leave a space after the single-line comment character. For example:

1	// this is comment

• Always leave a space before the Terminator of the multiline comment (to align the asterisk). For example:

123	/*                             */

• Do not write comments at the start of a multiline comment, the line where the Terminator is located. For example:

123	/* start                            end */

1234	/*here is line 1here is line 2 */

• Do not write meaningless comments. For example:

12	// 初始化value变量为0varvalue = 0;

• If a piece of code has functionality that is not implemented or needs to be perfected, a "todo" tag must be added, and a space should be left before and after "Todo". For example:

1234	// TODO 未处理IE6-8的兼容性functionsetOpacity(node, val) {    node.style.opacity = val;}

Document Comments

The document comments will appear in the API documentation in a predetermined format. It begins with "/**" and ends with "* *", with each line beginning with "*" (all aligned with the first "*" of the start character), and leaving a space between the comment content and the "*". For example:

123	/** * comment */

A document comment must contain one or more comment labels.

• @module. To declare a module, use:

1234	/** * 模块说明 * @module 模块名 */

For example:

1234	/** * Core模块提供最基础、最核心的接口 * @module Core */

• @class. To declare a class, use:

12345

/** * 类说明 * @class 类名 * @constructor */

@class must be used with @constructor or @static to mark non-static classes and static classes, respectively.

123456

/** * 节点集合类 * @class NodeList * @constructor * @param {ArrayLike<Element>} nodes 初始化节点 */

• @method. To declare a function or class method, use:

1234567

/** * 方法说明 * @method 方法名 * @for 所属类名 * @param {参数类型} 参数名 参数说明 * @return {返回值类型} 返回值说明 */

When @for is not specified, this function represents the global or module top-level function. When a function is a static function, @static must be added, and @param must be used when the function has arguments, and @return must be used when the function has a return value.

1234567

/** * 返回当前集合中指定位置的元素 * @method * @for NodeList * @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数 * @return {Element} 指定元素 */

• @param. Declaring function parameters must be used in conjunction with @method.

• The corresponding format is used when the parameter has the following conditions:

1

[参数名]

• Parameters have default values:

1

[参数名=默认值]

@property. To declare a class property, use:

1234	/** * 属性说明 * @property {属性类型} 属性名 */

Js/javascript Code Comment Specifications and examples