【学习笔记】JavaScript编码规范- 注释

多行注释使用/**……*/，需要包含一个描述，所有参数的具体类型的值还有返回值。

// bad
// make() returns a new element
// based on the passed in tag name
//
// @param {String} tag
// @return {Element} element
function make(tag) {

// ...stuff...

return element;
}

// good
/**
* make() returns a new element
* based on the passed in tag name
*
* @param {String} tag
* @return {Element} element
*/
function make(tag) {

// ...stuff...

return element;
}

单行注释使用//，把单行注释放在语句的上一行，并且在注释之前空一行。

// bad
var active = true; // is current tab

// good
// is current tab
var active = true;

// bad
function getType() {
console.log('fetching type...');
// set the default type to 'no type'
var type = this._type || 'no type';

return type;
}

// good. God Bless!
function getType() {
console.log('fetching type...');

// set the default type to 'no type'
var type = this._type || 'no type';

return type;
}

如果你指出的问题需要重新定位或者提出一个待解决的问题需要实现，给注释添加FIXME or TODO 前缀有利于其他开发者快速理解。这些注释不同于通常的注释，因为它们是可实施的。这些实施措施就是FIXME -- need to figure this out or TODO -- need to implement.

function AAA() {

// <strong>使用// FIXME:给一个问题作注释 </strong>FIXME: shouldn't use a global here
total = 0;

return this;
}

function BBB() {

// <strong>使用//TODO:给问题解决方案作注释 </strong>TODO: total should be configurable by an options param
this.total = 0;

return this;
}

God bless You!