Javascript 编程规范(5)

参数

1. 简单类型
   简单的类型的参数可以直接在函数参数定义中注释说明。
   function(/*String*/ foo, /*int*/ bar)...
2. 可变类型参数
   下面是几个修饰符供参考：
   • ? 可选参数
   • ... 说面参数范围不确定
   • [] 数组
     function(/*String?*/ foo, /*int...*/ bar,
     /*String[]*/ baz)...
3. 全局参数描述
   如果你想增加一个描述，你可以将它们移至初始化块。
   基本信息格式为： *关键字* 描述字段 （ *key* Descriptive sentence）
   参数和变量的格式为： *关键字* ~*类型*~ 描述字段 （ *key* ~*type*~ Descriptive sentence）
   注： *关键字* 和 ~*类型*~ 可以使用任何字母和数字表述。
   function (foo, bar) {
       // foo: String
       //  used for being the first parameter
       // bar: int
       //  used for being the second parameter
   }

变量

由于实例变量、原型变量和外部变量的声明是一致的，所以有很多的方法声明、修改变量。具体的如何定义和定位应在变量最先出现的位置指明变量的名称、类型、作用域等信息。

function foo() {
    // myString: String
    // times: int
    //  How many times to print myString
    // separator: String
    //  What to print out in between myString*
    this.myString = "placeholder text";
    this.times = 5;
}

foo.prototype.setString = function (myString) {
    this.myString = myString;
}

foo.prototype.toString = function() {
    for(int i = 0; i < this.times; i++) {
     dojo.debug(this.myString);
     dojo.debug(foo.separator);
 }
}
foo.separator = "=====";

对象中的变量注释

应使用和对象值和方法一致的标注方式，比如在他们声明的时候：

{
    // key: String
    //  A simple value
    key: "value",
    // key2: String
    //  Another simple value
}

返回值

因为函数可以同时返回多个不同（类型）的值，所以应每个返回值之后加入返回类型的注释。注释在行内注释即可，如果所有的返回值为同一类型，则指明返回的类型；如为多个不同的返回值，则标注返回类型为"mixed"。

function() {
 if (arguments.length) {
  return "You passed argument(s)"; // String
 } else {
        return false; // Boolean
    }
}

伪代码（有待讨论）

有时候您需要在函数或者类中添加对于此函数和类的功能性流程描述。如果您打算这样做，您可以使用 /*======== （= 字符最好出现 5 次或者更多），这样做的好处就是可以不用将这些东西加入代码（译注：原作者的意思可能为代码管理系统）。

这样看起来在 /*===== 和 =====*/ 会有非常长的一段注释，等待功能调整完毕以后就可以考虑是否删除。

/*=====
module.pseudo.kwArgs = {
 // url: String
    //  The location of the file
    url: "",
    // mimeType: String
    //  text/html, text/xml, etc