关于《Javascript编码规范》注释部分的讨论 about edp HOT 12 CLOSED

1. 关于文件注释：我觉得应该合成一块。现在相当于Copyright和文件信息分开了
2. 可选形参是否需要opt_开头，如果需要的话，那object里的可选项貌似也要opt_开头了，太麻烦。。。我建议还是通过注释解决。虽然我自己以前也在北北影响下使用了opt_
3. Object类型参数，里面的项怎么注释？@config，还是obj.property？

关于gcc的注释规范，我不清楚和jsdoc的区别点有多大，但看起来，type那块，至少{(number｜boolean)}和{?number}之类的是不兼容的。这块是否需要统一？

from edp.

1. 文件注释很可能关系到svn的hook的实现，该怎么写还是怎么写吧……

2. 关于_opt的问题，我的理解是这样的

   如果是可选参数，强制要求加_opt（关系到closure compiler的压缩），但是这一参数仅有2种情况：

   • 这个参数直接传递给某个函数，则保持不变，callAnotherFunction(a, b, opt_c);
   • 这个参数参与函数本身的逻辑，则必须写var c = opt_c || defaultValue;把opt_c变成c，免得满眼opt_的，同时也强制要求有默认值了。

3. 暂时没用jsdoc注释，全是普通注释的，这个无建议……

from edp.

提一个问题，如何记录文件的版本更改，是开发者从svn上自己找，还是在注释中声明？

是否每次修改都要改文件的**@revision**字段？

上一份后端的注释：

* @author guojichun
* @since 1.0.0 列表页查询功能 增加广告位类型、尺寸查询反馈结果，增加size参数，取广告位表里面用户使用的广告位尺寸信息 by chunping 2010-06-09<br>
*        1.1.0 refactor by gmz
* @version 1.3.5 参数增加channelGroups by jicansheng

这些是否我们也要？

from edp.

是否每次修改都要改文件的**@revision**字段？

关于这个问题，我觉得是版本控制系统的-m就好。否则，就相当于一次修改内容写两处了

from edp.

那我觉得，关于_opt的问题，可以不强制_opt，但可选参数的注释必须标明是可选的。

from edp.

/**

• @constructor
• @extends {Person}
  */
  function Baiduer() {
  Person.call(this);
  // constructor body
  }
  baidu.inherits(Baiduer, Person);

Baiduer.prototype = /** @Lends {Baiduer} */ {
constructor: Baiduer,
_getLevel : function() {
// TODO
}

}

这段代码，貌似baidu.inherits(Baiduer, Person);需要写到重写原型的后面啊。
打个比方，Baiduer通过baidu.inherits继承了Person的原型方法getMoney，此时重写Baiduer.prototype，这里之前继承的getMoney方法就丢了。

from edp.

这段代码，貌似baidu.inherits(Baiduer, Person);需要写到重写原型的后面啊。
打个比方，Baiduer通过baidu.inherits继承了Person的原型方法getMoney，此时重写Baiduer.prototype，这里之前继承的getMoney方法就丢了。

baidu.inherits应该在Baiduer.prototype = {...}后面调用。如果先baidu.inherits了，那后面应该Baiduer.prototype.method =。
另，对于上面这种情况，直接Baiduer.prototype =或者Baiduer.prototype.method =的，不用@Lends了哈。

from edp.

变量必须（MUST）即用即声明，不得（MUST NOT）在函数（或其它形式的代码块）起始位置统一声明所有变量。

这个是不是有问题？使用前先声明是好习惯，在起始位置统一声明也许是没有必要的，但也许不至于说要完全禁止。

而且这个规范很难执行，即用即声明，如何界定"用"? 那如果 var a = 0; 也能说用了，用来干嘛呢？用来赋值为0。

变量之间往往有关系， 集中定义在一起可以从逻辑上简化理清这些变量的关系，是有益的，而且我也不明白这么做带来的坏处是什么。

from edp.

@wurongyao

如何界定"用"? 那如果 var a = 0; 也能说用了，用来干嘛呢？用来赋值为0。

关于这个问题，有点抠字眼了。所谓的用，我下个不科学不权威的定义，是指在完成目的相关的语句或表达式中发挥作用。var a = 0充其量算声明＋初始化。就像一个类，我们不可能初始化实例了，就说你用了它。

@otakustay 提出即用即声明，主要还是减少变量跨度。

var list1 = getlist1();
var list2 = getlist2();
var len1 = list1.length;
var len2 = list2.length;

for () {
    // loop list1
}

for () {
    // loop list2
}

对于上面的代码，list2和len2就不是即用即声明的。如果第一个for跨越了半个屏幕高度，那阅读的人看第二个for的时候，就会奇怪list2和len2从哪来的。如果起头定义10个变量，那怎么理解，难道他们全部都会马上使用？

刚好上面两位都是写过c#，并且在上海待过的同学。我就抛一个问题，下面的代码你们会怎么写，选a还是b？答案应该不要太容易。

// a:
for ( int i = 0; i < 10; i++ ) 
{
}

// b:
int i;
for ( i = 0; i < 10; i++ )
{
}

from edp.

对于这个问题，我经过和不少人的讨论，大致觉得是这样的。

统一声明的优点：

• 容易找到一个使用中的变量的作用域，不是在当前函数的头部，就是在上层函数的头部。
• 对于非常优质的代码，光看声明的变量就大致能推测出逻辑，这是上研一位T4的同学说的，我并没有见过太多这样的代码

即用即声明的优点：

• 删除一个变量的使用时，会很顺手的删掉其声明，不会留下一个空的声明但又不知道这个变量下面到底有没有用过，要看一遍整个函数才能确认是否可删
• 对于有初始值的变量，基本一眼就能看到声明的语句，容易确定
• 对于for循环这类的i、length等，我觉得统一声明在函数头部是一件很傻冒的事

关于即用即声明如何鉴定，如楼上所述，我认为这虽然并不是一个非常客观的定义，但作为一个合格的前端工程师，只要不是钻牛角尖，应该很容易识别。

当然并不排斥一些在整个函数中跨大块逻辑段都会用到的变量，在函数头部或尽可能早地位置进行声明，比如在整个函数逻辑中经常要show或hide的DOM元素之类的。

from edp.

举了 var a=0;这个作为例子的确是钻牛角尖（丢人了），不好意思。

但其实我想表达的是赋值运算某些情况下也能算“用“，不光光是无聊的赋值这么简单，有的时候是为了归类或者理清逻辑。
因为变量之间往往会有关系。
如：
var a = 100 ;
var b = funA( a ) ;

可能b暂时不会被用到，但由于和a有联系，写在这里似乎又是理所应当的。

假设代码很长，当 a 被用来干了很久甚至加班以后，b才出现了。然后很久以后又用到了b的哥们c。

var a = 100 ;
..... 很多很多行用到 a 的代码..............

var b = funA( a );
..... 很多很多行用到 b 的代码..............

var c = funB( b );
..... 很多很多行用到 c 的代码..............

在用到c的过程中会发现，咦？c是干嘛的？然后往上看，哦，那b是？那a呢？结果又得往上找（冒泡），然后看完a再接着来回味b,然后再回到c（捕获）。
这种多次查找比一次查找要更痛苦，尤其对于记性不太好的同学。

还有一种有关联的情况就是某变量的值与传进来的参数有关。
如 function test ( x, y ){
var b = ( x + y ) / 2 ;
....................
}

则无论b会在多么遥远的地方才会被用到，也应该在看得见x和y的地方定义为好，否则又会经历一次冒泡与捕获的痛苦。

而且变量定义在一起还有一个作用，就是防止重复定义，便于维护。
最常见的就是类似

var slice = Array.prototype.slice ;
var concat = Array.prototype.concat ;

我想当人们看到这种代码的时候，也没想过它们定义后会被马上使用。可是你要分开写，就很别扭。
说白了，这些都是全局性的东西。

for while 这种需要定计数器的，是的确不适合在外面定义，
因为它也没想跟外面发生什么关系，它只是个计数器。

如果在最开始定义，var i =0; var j =0 ; 是很奇怪，而且要写注释都不知道该怎么写。总不能写成”某循环计数器“

我甚至见过由于之前定义并赋值了，for循环的定义那直接就省了,
写成了
var i =0;
for ( ; i < len; i++ )

如果之后又来了一个循环，且在看不到上一个for循环代码的遥远地方，再加上记性不好，
也写成 for ( ; i < len; i++ ) , 那基本就完了。

我的观点是：

1. 对于有关联的变量，或者同一种类型（如都是正则表达式），可以声明在一起。
2. 当一个变量的值依赖于传进来参数时，最好在函数最顶上挨着参数写。
3. 对于全局变量，应该在最开始声明。
4. 对于for while 这种需要自己特别定制，且防止被其他地方玷污的变量，必须要即用即声明。
   (这种变量往往连个像样的名字都不会有，不是叫 i ,就是叫 j ,也不好意思出去见人)

我在写C#的时候，也是这么写的。

所以，对于 变量的即用即声明 是否要 MUST ，还是应该进一步细化一下，我暂时还是持保留的态度。

from edp.

@wurongyao

恩，很多场景确实存在，对于你观点中的1，我觉得不够具体，当然，可以再商榷。
我新建了一个issue，这个issue只是讨论注释的地方，而且最近质疑的声音不少，可以开发让大家提出有理有据的声音。

#6

这个issue，我就close了。观点给你转移过去

from edp.