黄金定律——不管有多少人共同参与同一项目，一定要确保每一行代码都像是同一个人编写的。
注释规范
编码规范中有一条很重要---见名知意，有时候直白的函数名还不能表达完整的意思，这个时候注释就出场了，代码是由人编写并维护的。请确保你的代码能够自描述、注释良好并且易于他人理解。好的代码注释能够传达上下文关系和代码目的。
在写代码前就应该添加注释，这时在你的脑子里的是清晰完整的思路。
如果在代码最后再添加注释，它将花费你双倍的时间。
注释的写法
-
html
<!-- 注释的内容 --> -
css
/* declarations */ -
javascript、less
// 注释内容 /* 注释内容 */
通用
注释尽量使用英文来描述
单行注释
- 双斜线后，必须跟注释内容保留一个空格
- 可独占一行, 前边不许有空行, 缩进与下一行代码保持一致
- 可位于一个代码行的末尾，注意这里的格式
// Good
if (condition) {
// if you made it here, then all security checks passed
allowed();
}
var zhangsan = "zhangsan"; // 双斜线距离分号四个空格，双斜线后始终保留一个空格
多行注释格式
- 最少三行, 格式如下
- 前边留空一行
何时使用
- 难于理解的代码段
- 可能存在错误的代码段
- 浏览器特殊的HACK代码
- 想吐槽的产品逻辑, 合作同事
- 业务逻辑强相关的代码
/*
* 注释内容与星标前保留一个空格
*/
文件注释
/*
*@author: who are you
*@date: when you write it
*@description: the function of this file.
*/
多人合作注释
同一个文件的代码可能被多个人修改，这个时候需要标识出谁改动了哪些部分。
格式： // add begin by 作者名 ,一个分号;，再加上原因 Reason
代码添加的最后加上：//add end
Example
// add begin by liuxing ; Init post's id
var postId = 1;
//end add
或者
// add begin by liuxing
/**
* 多行注释来说明原因
*/
var postId = 1;
//end add
javascript 注释
文档注释
- 各类标签 @param @method 等 参考 http://usejsdoc.org/
- 格式如下
用在哪里
- 所有的方法
- 所有的构造函数
- 所有的全局变量
/**
* here boy, look here , here is girl
* @method lookGril
* @param {Object} balabalabala
* @return {Object} balabalabala
*/
- 常用tag
@author、@callback、@copyright、@default、@deprecated、@throws 、@todo
@param、@returns
方法与函数的注释
提供参数的说明. 使用完整的句子, 并用第三人称来书写方法说明.
/**
* 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) {
// ...
};
属性注释
也需要对属性进行注释.
/**
* Maximum number of things per pane.
* @type {number}
*/
project.MyClass.prototype.someProperty = 4;
枚举
/**
* Enum for tri-state values.
* @enum {number}
*/
project.TriState = {
TRUE: 1,
FALSE: -1,
MAYBE: 0
};
注意一下, 枚举也具有有效类型, 所以可以当成参数类型来用.
/**
* Sets project state.
* @param {project.TriState} state New project state.
*/
project.setState = function(state) {
// ...
};
Typedefs
有时类型会很复杂. 比如下面的函数, 接收 Element 参数:
/**
* @param {string} tagName
* @param {(string|Element|Text|Array.<Element>|Array.<Text>)} contents
* @return {Element}
*/
goog.createElement = function(tagName, contents) {
...
};
HTML注释
@todo 小帽
CSS 注释
@todo 惜玉
