编码与文档风格讨论

[lifesinger]

看了下大家的代码，为了保证整体风格一致，有些地方需要达成一致：

声明多个变量时的写法

如果是纯声明，或非常简短的赋值，可以写成一行。比如：

var cache, event, all, list, i, len, rest = [], args; 

如果赋值语句较长，目前有一种写法是用逗号换行：

var $ = require('jquery'),
        position = require('position'),
        useIframe = $.browser.msie && Number($.browser.version) < 7;

还有一种写法是直接用 var 风格：

var $ = require('jquery');
var position = require('position');
var useIframe = $.browser.msie && Number($.browser.version) < 7;

我建议直接用 var 风格呀，这样无论写起来还是修改都更方便，用 closure compiler 等压缩后，会自动变成上面那种逗号分隔的。

没记错的话，前面那种逗号风格的兴起，是 NCZ 在2009 年介绍 YUI Compressor 压缩原理时提到的：

http://www.slideshare.net/nzakas/extreme-javascript-compression-with-yui-compressor

NCZ 倡导：为了帮助压缩工具实现更好的压缩，倡导一个函数内，尽量只保持一个 var 和 return.

然而，目前高级压缩器，Closure Compiler 和 UglifyJS 等，都能自动处理 var 了，在压缩函数时，会自动做变量提升和 var 单一化。

因此尽量保持一个 var 的最佳实践，目前已不是最佳实践。大方向肯定是更人性化、更自然化的写法。优化交给工具就好。

最后，强烈建议：多个 var, 且非纯声明或简单赋值时，建议写成：

var $ = require('jquery');
var position = require('position');
var useIframe = $.browser.msie && Number($.browser.version) < 7;

[lifesinger]

文档中，中英文夹杂时的风格

我整理过一份文档：文档书写规范

最核心的两点：

1. 含有中文时，用中文全角标点。
2. 中文和英文之间，空一个英文空格。

相关讨论非常多，知乎上的一篇汇总：http://www.zhihu.com/question/19587406

我个人力挺这句话：

中文与西文混排时，不一定要有空格字符，但一定要有间距。

对于 github 上的 markdown 来说，目前的展现方式，只有加空格字符才能让中文和西文之间有一定间距，因此我强烈建议大家遵循上面那份文档书写规范。

[lifesinger]

目前最明显的就这两点，其他细节，接下来我会逐一看大家的代码，一起来讨论统一。

[vilicvane]

一般我进行变量声明的时候, 多是直接用var, 每行一个. 除了所声明的变量暂不需赋值, 并且有很明显的相关性的时候, 会进行分组, 比如:

var width, height;
var x, y, z;

[feiwen8772]

平时，两种混用的比较多，嘿嘿，一般把变量声明都放在代码块的头部，这个我比较注意，仅个人观点，欢迎大家拍砖斧正！

[baishuiz]

一般会用 var 做分组，同组变量用换行前置逗号隔开：

var width = width || '0px'
,height = height || '0px';

var x, y, z

[hotoo]

已经习惯单个 var 了，多个反而觉得别扭了，哈哈 :)

[majorye]

习惯在函数开始的时候，把函数里面需要的变量都var好，如果有group的概念，我喜欢放在一块，比如：
var height, width; // the property of the box
其他的，会3,5个一组，比如
var x,y ,z; // others

[nikejaycn]

确实，已经习惯了单个var，需要的变量都在函数的头部利用一个var定义好了。
中英文混杂的问题以后要注意一下了。

[caolvchong]

一般一行一个var（除了for语句），主要为了易读，缩写留给压缩处理：
var width;
var height;
for(var i = 0, len = arr.length; i < len; i++) {
}

下面这种写法不是很赞同，缩进和换行极容易被IDE格式化掉
var $ = require('jquery'),
position = require('position'),
useIframe = $.browser.msie &amp;&amp; Number($.browser.version) < 7;

项目中协作者之间最好用同一种格式化模板，协作时候减少大面积版本冲突

[kingfo]

1.事实上我是个习惯 var 和变量一一对应的即,

var a;
var b;
var c;
//...

当然这是在 as 编码上保留的习惯, 毕竟 as 由于‘强制类型’（可以强制弱类型），导致修改方便程度上来说也使得我养成了这样的习惯：

var a:String;
var b:Number;
var c:*;

当然，早期的团队，是被要求在 js 中尽量使用1个 var ，这是由于当时的条件和环境决定的，毕竟 as 是编译过后发布，而 js 当初没有，现在有工具可以优化，则尽量还原自己的习惯。

2.中英文之间的空格或者视觉空间现在是刻意保留的，这样使得行文看上去更美观些。至于是否有具体的空格符倒是没被刻意强迫自己，毕竟行文环境的字体决定了。当然最后实践的感觉还是最好能够加上空格，以使得在不同的行文环境中展现近似。

• 题外话，是否讨论下 Tab 制表符规范？现在我已经尽可能的使用4个空格代替制表符。这样的目的也是在文本在不同的行文展现环境下保持格式一致。 当然这部分之后通过会工具进行以人为层面的适应。

总之，只要写给人用的，就让他更直观和易修改的同时适应各种行文呈现环境就好了。

[lifesinger]

还有一个需要讨论的是：

注释风格

是 YUI 式的 JSDoc 风格？还是 Backbone 式的说明式风格？

YUI 式风格

典型代码：

https://github.com/yui/yui3/blob/master/src/dom/js/dom-core.js

特点：清晰，但啰嗦，比如参数 element, className 等，一看得知道是什么含义，但每个函数前面还得加上那么一行一模一样的注释，看着揪心。YUI 里，还有一些文件里有大段没代码的注释，纯粹是为了生成文档用的，蛋疼。

关于注释的谎言，《Clean Code》 一书有非常精彩的论述，借用下阿当的感悟：

事情从我和@flashlizi 讨论注释是否必要开始。在我开始编程的初期，我接触过很多质量非常烂的代码，没有注释，命名随意，奇技淫巧遍布 —— 不只是别人的代码，也有我自己几个月前写的。我深知代码缺乏可维护性，可读性是件多么可怕，多么让人讨厌的事。当时我能想到的解决方法就是注释。听到这么一句话“好的代码，注释应该占去三分之一的篇幅”，当时我很认同，在之后相当长的一段时间里，我也一直把这个当做是可维护性、可读性的最佳实践，甚至在我自己写的书里，我也将这句话记了上去，希望让更多的人能听到这句话。

直到有一天，我读了《代码整洁之道》（原名：《clean code》）这本书。书中的观点彻底颠覆了我对注释的信仰。书里提到"注释会随着功能的修改而慢慢腐坏，充满谎言"，“只有代码本身才是最可信的”，“绝大部分的注释都可以通过好的命名或者开发工具例如svn来代替”，我很认同，就在我信奉注释的力量的几年里，注释其实并没有像我想像中那么强大。人无法回避的问题是人性，人不是机器，人有惰性，有时间压力，还有离职入职接手别人的代码，所以维护注释其实是非常需要过人的毅力，甚至道德的，“始终维护注释的高质量”这个要求甚至是反人类的。人们总会乐观地想“只要我坚持下去，只要我一直保持高度自律，就可以保证它不会腐坏”，事实上，这样的想法真的是过于乐观了。想想看，你有多少次强迫自己养成某个好习惯了 —— 晨跑？学英语？减肥？你坚持下来了吗？这就是人性，反人性的做法其实是很难坚持下来的，无论在初期你有多么强的信念。

Backbone 式的注释

Backbone 的代码，采用了说明式注释，在每个需要说明的方法或代码段前，会写上一两句话，描述下面的代码是干嘛的。典型代码：

https://github.com/documentcloud/backbone/blob/master/backbone.js

这种风格，也能很方便的生成文档：

http://documentcloud.github.com/backbone/docs/backbone.html

虽然针对各个方法的注释，也会有一些啰嗦重复（比如前面一个方法是 setXxx, 后面一个方法是 setYxx, 两者的注释大同小异），但由于摆脱了 JSDoc 的禁锢，不用再去描述参数名，这样已经大幅度降低了注释的重复率，同时也让注释的腐坏变慢，至少比 JSDoc 式注释慢很多。同时又能生成一份可读性不错的文档，因此我觉得这种风格是值得推荐的。

大家都编写了好几年代码了，各自对注释的感觉如何？说说你的看法。

[hotoo]

缩进的风格确实需要统一一下，我个人支持 4 个空格的缩进方式。
Eclipse 可以定义格式配置文件，其他人导入即可。
针对 Vim，在 vimrc 中设置：

set softtabstop=4
set expandtab " replace tab to whitespace.
set tabstop=4 " show tab indent word space.
set shiftwidth=4 " tab length

如果遇到空格和 tab 混合的情况，可以执行 :retab

[e7h4n]

之前编写过一个比较大的模块，我的注释风格是，所有对外提供的 API，使用 jsdoc 注释。除此以外的则使用 Backbone 式（没 Backbone 那么啰嗦）。主要是有以下考虑：

• jsdoc 自动生成的文档对于和组外人员沟通和约定非常有用
• 普及 jsdoc 八股文一样的注释风格让人感觉非常蛋疼
• 除此以外的其他注释应该解释 why 而不是解释 what 和 how

但是 Backbone 的注释风格本身也很啰嗦，就像 Clean Code 里面说的，没人维护的注释是 evil。所以我更喜欢用代码本身来自解释，相对于注释来说，代码本身更可靠。比如这段代码：

    // if someArray has a valid item
    if (someArray.length > 0 && someArray[0].isValid) {
        doSomeThingWith(someArray[0]);
    }

我更喜欢这样写：

    var isHasValidItem = someArray.length > 0 && someArray[0].isValid;
    if (isHasValidItem) {
        doSomeThingWith(someArray[0]);
    }

[fundon]

已习惯了第一种写法，开发过程中会使用第二种过度下，发布时会强制写成第一种。强迫症呀

[pierrewrs]

对外开放的接口，各种类和构造器、公用方法建议使用多行注释的方式， YUI 式的，维护起来也还好啊；
实例属性及私有方法等，可以简单的单行注释交代一下， Backbone 式的，描述清楚即可。

[edokeh]

可是backbone注释生成的文档没办法立刻给使用者一个整体的认知，对日后查找翻阅api也基本没啥帮助

[e7h4n]

@edokeh “立刻给使用者一个整体的认知” 我想要通过注释和 API 文档以外的方法来做到，比如一个良好的 tutor 和 demo。

[edokeh]

@perfectworks
但是你代码变了之后，除了修改注释，还需要去改tutorial
用jsdoc的话，在一定程度上你不用额外再去写tutorial

[lepture]

@edokeh 我觉得这不是问题，良好的文档是开源必备的，单纯的开放代码并不能称为开源。

[fool2fish]

通常代码中都会有backbone风格的注释，但是一旦要提供api文档，还是需要jsdoc风格的注释的，不然手工api文档更不靠谱

[jayli]

感觉写代码尤其是js随意一些为好，工作压力已经够大了，代码整洁程度要求太严苛，效果不一定好哪里去，呵呵，不如只约定接口和数据格式，比直接约定编码规范更直接一些。

[jayli]

https://github.com/jayli/javascript.patterns/blob/master/chapter2.markdown 这里提到单var模式的好处和分散var的缺点

[lifesinger]

@fool2fish 我比较反对为了文档而文档，YUI 的 API 算是做得非常好了，但实际上，在使用时，真遇到问题，还得去看它的源码实现。而对于初中级用户，更有效的文档是 Tutorials 和 User Guides, API 并不适合直接阅读，查阅的话，又没有源码那么清晰不说谎，个人觉得 JSDoc 生成的文档是比较鸡肋的。

反观目前很多流行社区的趋势，比如 nodejs, jquery 等等，都是人肉 API 的，但质量都很高，API 文档的可读性也远比 JSDoc 生成的强。维护成本上，特别是 jQuery 的，个人觉得明显比 YUI 的成本低，但 jQuery API 的效果好很多。

JSDoc 带来的问题，是：

1. 让写代码时不能专心写代码。软件界有一个核心思想是“解耦”，这个解耦，我觉得应该也包括 编写代码 和 书写文档 的解藕。不用 JSDoc，可以让开发者在写代码上更专注于写代码，在写文档时则更专注于写文档，效果往往更好。
2. JSDoc 还有一个问题是带来大量重复。有些参数说明，上一个方法和下一个方法明显是一样的，但为了 JSDoc，你得复制一份甚至10份，这样，当该参数发生变化时，得批量搜索替换，有违背尽量减少重复的原则，充满着坏味道。

Backbone 等社区倡导的注释风格，个人觉得在目前是一种比较好的权衡。Backbone 类注释，遵循：

1. 从帮助用户阅读代码的角度来书写。有开、启、承、合，主要作用是阐述整体代码的结构，以及解释某些需要注意的代码的 why.
2. 如无必要，勿增注释。如有必要，则注释必不可少。这是一种权衡，虽然目前尚无明确的标准，但个人感觉这个方向是对的。

[lifesinger]

@jayli 不同意写代码尤其是 js 还是随意一点好的观点，这会导致以下问题：

1. 当我需要 review 其他人的代码时，如果格式排版乱糟糟的，很不符合自己的习惯，那么经常会没什么心情去看了。心情是很重要的。
2. 多人同时维护同一份代码时，如果彼此风格缺少基本的一致性，修改代码时，彼此会调整格式就浪费不少时间，不值得。
3. 很同意 js patterns 一书中的观点：

可维护的代码意味着代码是：

可读的
一致的
可预测的
看起来像是同一个人写的
有文档的

太随意了，会影响可读性、可维护性，不好。

[lifesinger]

@jayli js.patterns 一书里关于单 var 模式的文字，个人觉得太偏颇，太 old. 更人性更理想的一种情况是：

1. 按需 var, 需要时才声明，让变量声明和使用它的地方尽可能靠近。这样，以后要移除某段逻辑时，只需要关注某一段代码即可，做代码重构（比如提取函数）时，也更方便。
2. 多 var 模式，更符合直觉，代码更不容易出错。比如对变量声明进行修改、移动时。下面这种错误，在淘宝时就不止碰到一次：

var a = 1,
      b = 2;
      c = 3;

js.patterns 一书里，提到的四点好处：

在函数的顶部使用一个单独的var语句是非常推荐的一种模式，它有如下一些好处：

1. 在同一个位置可以查找到函数所需的所有变量
2. 避免当在变量声明之前使用这个变量时产生的逻辑错误（参照下一小节“声明提前：分散的 var 带来的问题”）
3. 提醒你不要忘记声明变量，顺便减少潜在的全局变量
4. 代码量更少（输入更少且更易做代码优化）

第一点很同意，是个优点，可以让阅读者立刻知晓该函数的数据结构类型，但这个好处，一般人体会不到。

第二点没意思，“在使用变量前必须声明变量”，这个是常识，但未必需要通过单 var 模式来保证，和 单 var 模式没什么必然联系。

第三点也是瞎扯，该忘记的还是会忘记，不会因为函数头部有个 var 就不忘记。我倒觉得，多 var 模式更让人会记得声明（只要看附近有无声明就好）

第四点是老旧观点了，强烈反对。代码量的优化，请通过工具来做。

后面提到的分散 var 带来的问题，其实并不是分散 var 带来的，而是没做到“在使用变量前必须声明变量”导致的，js.patterns 把问题转移了，鄙视这一段的逻辑呀。

[lifesinger]

@jayli 突然对 JS.Patterns 这本书感兴趣了，阅读了《高质量JavaScript基本要点》一章，对不少章节的观点表示很不同意。

1. 单 var 模式。除了同意“在同一个位置可以查找到函数所需的所有变量”这个优点，其他的都转移了话题，不同意。
2. for 循环。我们已经在远离 IE6-7 了，特别是 mobile 端开发。len = xx.length 的做法，一般情况下没有性能问题。HTMLCollection 需要提前拿到 length，性能是一方面，更顾虑的是因为 HTMLCollection 是 live 的，避免逻辑错误甚至死循环等。

i++ 改成 i += 1 真蛋筒呀，老道的 jslint 不是神器，不能为了工具而改变习惯。

后面的小改进最好忘掉。可读性最好的，依旧是 for(var i = 0; i < array.length; i++) { ... }

1. for-in 循环。蛋筒的 hasOwnProperty, 有时候是必要的，但一碰到 for-in 就加上，则是蛋筒的厉害，比如：

function doSomething(options) {

    for(var p in options) {
        if (options.hasOwnProperty(p)) {
             // do sth.
        }
    }

}

在实际使用时，options 几乎 100% 都是一个纯的 { xx: yy } 形式，而目前如果你不是还在用老旧的 Prototype 等类库的话，谁也不会闲得蛋筒给 Object.prototype 增加自定义属性。加上这么一道限制，在实际项目中，并不会增加可靠性。

真想追求 0 bug 的话，还得考虑 IE 下的 Dont Enum bug, 在 IE 下，如果 options 有个 { "toString": xx } ，for-in 循环时，是获取不到 toString 键值的，此外还有 valueOf 等等，得打补丁。

即便考虑了 Dont Enum Bug, 也未必就 0 bug 了，options 还可能自己定义了 hasOwnProperty 方法，这样，你得写 Object.prototype.hasOwnProperty.call(options, p) 来保证没问题。

问题是，这条道永远没个尽头，来一个 window.Object = null, 立刻所有 JS 代码都哭了-,-

很多很多时候，hasOwnProperty 是个美丽的废话。当然，在必须用的时候，你不能少。比如遍历某个 obj，这个 obj 是继承自 Dog，Dog 又继承自 Animal 时。但如果 obj 只是 { ... }, 就忘记 hasOwnProperty 吧。

此外，hasOwnProperty.call(o, p) 的性能，不如 o.hasOwnProperty(p), 真要为了性能，请大道至朴，最直白最符合直觉的往往最好，因为 JS 引擎优化最多的地方，就是大家最经常的用法。

1. 好的注释就一句话可描述：as short as possible, but as long as necessary.
2. 强烈反馈生成 API 文档。注释就是被这些工具搞坏的。fuck!!!

吐槽太多不利身心健康，越来越感觉 jQuery, NodeJS 等社区，把 YUI 等社区抛了好远好远了，从理念更新到代码实现！

回到本议题的主题：注释。

核心的是：

1. 关注点分离。让写代码时好好写代码，不被注释禁锢和打扰。
2. 源码文件就如浏览器，IE10 的口号是 Less browser, more web. 这口号真好呀，对于编码来说，我觉得是时候说：

Less comments, more code

了。

[lifesinger]

这篇文章很好：

http://benalman.com/news/2012/05/multiple-var-statements-javascript/

[antife-yinyue]

关于var，以前我死苛成一个，现在基本多行。只声明的话，和玉伯一样，会单行，有必要也会分组。
关于缩进，我只能用空格，2个。

[antife-yinyue]

大侠们怎么看 for (var i = -1, len = array.length; ++i < len;) {}

[lifesinger]

@jsw0528 除了某种特殊需求，需要从后面开始算，否则还是 i = 0 开始好了。

[iwege]

@lifesinger 关于在顶部声明变量的问题，我们在实际上碰到的问题就是需要使用那种规范去解决。这关键不是规范老手（当然老手会觉得old），而最关键的是完全不懂得的新人。
最简单的一个例子：

function(){
.....
if(something){
   var a = 0;
}
.....
a = 1;
....
}

这是一个典型的新手所犯的错误，如果恰好这个新手在开始就很喜欢写长段的代码，你要定位这个错误就有点困难了。用开头定义全部的变量可以在review的时候更容易找到这个变量定义的位置，也马上明白这个是全局变量还是局部变量。

至于是单行还是多行...这个就让写的人自己纠结吧。不写注释简单测试单行就搞定了，需要多注释的，尽量的用多行方便书写注释。

另外还有：

for(int i = 0 ...){

}

或许也就只有你们这些高端的前端不会出现这个问题，但是至少在我这边被问到了三次了，之前他自己碰到了几次可想而知。

[pierrewrs]

@jsw0528 这个太奇技淫巧了吧
len先赋值还可以采纳, 避免外部对象发生改变导致的非预期死循环之类的, index 从 -1 开始就是搞笑了, 难道内文不用或者喜欢二次加工? 与其这样不如直接先 var 然后再 while 了.

另外关于编码风格, 除了基本命名规范和约定, 其他交给 IDE 的格式化器来做绝对省时省力啊. 本来就是团队协作开发, 让大家提交前用统一的格式化器预处理一下, 应该很顺当啊, 手工作坊式的十八班兵器也照常用就是~

[xiongsongsong]

@iwege
这不能称为新手犯的错误吧，因为有时候这么写也未尝不可。
至于review时不好找变量定义的位置，感觉是工具选择的不对。例如webstorm,点击某个变量，则会自动高亮所有使用到的地方，Ctrl+点击变量，则会自动跳转到定义处。

[iwege]

@xiongsongsong

感谢您的提醒，不过我提出来这个场景，只是想要说下实践当中遇到的问题以及顶部声明对这个问题场景的好处。如果都是熟手行家，自然无规范也能跑通，只是我这边大部分都是新人没怎么接触过JS的，碰到的问题也多是诸位从来没犯过的。

让诸位前端高手见笑了，我们还在用着效率低下的无语法检查的编辑器（比记事本稍稍好点）。但是这条规范对我们这种前端新手的帮助很大，排查错误也很方便。

[kingfo]

关于注释及其api文档，最反人类的是明明工程师最求的类似 code less do more （懒呗） ，而注释及文档很多时候无论撰写时还是维护，都是相反的。
个人遵循：

1. 代码尽可能阐述直白，说明 what。
2. 为了防止直白照成的类似非常长的命名则尽可能的让每个变量尤其是函数实现简单，低耦合高内聚类似的思想也是适合撰写函数的。
3. how 部分会写在 demo 中。demo比文档诚实，只要你的代码保持最新就能够展示。（为什么不是单测？那是因为这个面向的是用户不是开发者哟。）
4. why 则会写在类似 getting started 等 tutorials 中。

总之一份好的文档就是扼要说明+丰富demo，而不是充斥着各种文字或者文档工具的特殊符号。

[zhangchen2397]

这里我说一下另外一种写法习惯，就是在()和[]中是否需要在前后加一个空格
在看jQuery源码的时候看到有这样的写法：

if ( something ) {
    var arrayA = [ 'a', 'b' ];
}

methodA( {
    'name': 'zc',
    'age': 25
} );

大家赞成这种写法么，这样看起来代码不会显得太拥挤。

[majorye]

@lifesinger 其实对于使用者而言，最重要的是Demo. 在使用一个你不熟悉的东东时，如果里面的Demo运行没有错误，而且能match 到50%的场景，那就是太美了.

[majorye]

对于注释， 其实我很鄙视在代码中看到中文注释，看着就不爽。而且本身对于developer而言，是需要每天都学习英文的。建议注释全英文化.

[antife-yinyue]

@zhangchen2397
我是习惯这样

if ( xx ) {
}
else {
}

但 gjslint 通不过，挺郁闷的～

[lepture]

编码风格的讨论可以结束了。请参考 JavaScript 编码风格

最终讨论的结果是，单 var 多 var 都可以接受。

@baishuiz 不推荐使用 npm style 的逗号与分号，不符合自然人的审美，纯粹为了方便删除。

[lifesinger]

issue 关闭。

已整理到 Wiki 文档：

• JavaScript 注释规范
• 文档书写规范
• JavaScript 编码风格

请 Arale 项目成员严格遵守。

[yolio2003]

精彩的讨论呀,对于
{
a
,b
,c
}
没有人有爱么?
觉得这样要好很多 忍不住,投一票

[lifesinger]

没爱

用人肉搞定本应该工具去搞定的事，不好呀

On Thu, Sep 6, 2012 at 4:37 PM, tcdona [email protected] wrote:

精彩的讨论呀,对于
{
a
,b
,c
}
没有人有爱么?
觉得这样要好很多 忍不住,投一票

—
Reply to this email directly or view it on GitHubhttps://github.com/alipay/arale/issues/36#issuecomment-8325997.

王保平 / 玉伯（射雕）
送人玫瑰手有余香

[lepture]

@tcdona

@baishuiz 不推荐使用 npm style 的逗号与分号，不符合自然人的审美，纯粹为了方便删除。

[lepture]

虽然离职了，但是还是把 issue 里的所有链接都修正了。

[lifesinger]

感谢晓明，你永远在我们心里。

On Wed, Dec 11, 2013 at 12:12 PM, Hsiaoming Yang
[email protected]:

虽然离职了，但是还是把 issue 里的所有链接都修正了。

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/36#issuecomment-30292642
.

王保平 / 玉伯（射雕）
送人玫瑰手有余香

[semious]

记得john说过javascript像一个nijia，本人同意这个观点。javascript不是浪人，完全一个人，不受任何约束，也不是武士，具有非常严格的风范。nijia是一个有组织，但是又不失个性特点。个人觉得，编写代码规范也应该是类似，不要太死，也不能太没有规范，而是一个得到大家认可的一种约定，一种默认觉得还行的东东。一种框架性的规范，而不是具体一定要如何如何。代码和文档的规范是一种compromise,一种基本的认可。

[zmofei]

backbone 风格的注释生成文档的话有什么工具推荐么？
http://documentcloud.github.com/backbone/docs/backbone.html