Dojo Javascript 编程规范 [4]

注释

生涩的代码就 没有必要 添加注释了，首先您需要 重写 它们。

所有的注释请使用英文。

从已解决的方案到未开发的功能，注释 必须 与代码相关。

大量的变量申明后 必须 跟随一段注释。

注释需要说明的是代码段的用处，尤其是接下来的代码段。

注释 没有必要 每行都添加。

文档

下面提供了一些基本的函数或者对象的描述方法：

总结（summary）: 简短的表述此函数或者对象实现的目的

描述（description）: 对于此函数或者类的简短的描述

返回（return）: 描述此函数返回什么（并不包括返回类型）

基本函数信息

function(){
　　// summary: Soon we will have enough treasure to rule all of New Jersey.
　　// description: Or we could just get a new roomate.
　　//　Look, you go find him.　He don't yell at you.
　　//　All I ever try to do is make him smile and sing around
　　//　him and dance around him and he just lays into me.
　　//　He told me to get in the freezer 'cause there was a carnival in there.
　　// returns:　Look, a Bananarama tape!
}

对象函数信息

没有返回值描述

{
　　// summary: Dingle, engage the rainbow machine!
　　// description:
　　//　Tell you what, I wish I was--oh my g--that beam,
　　//　coming up like that, the speed, you might wanna adjust that.
　　//　It really did a number on my back, there. I mean, and I don't
　　//　wanna say whiplash, just yet, cause that's a little too far,
　　//　but, you're insured, right?
}

函数的声明

在有的情况下，对于函数的调用和声明是隐义（invisible）的。在这种情况下，我们没有办法在函数中加入说明等（供程序调用）。如果您遭遇了这种情况，您可以使用一个类来封装函数。

注：此此方法只能在函数没有初始化的参数情况下。如过不是，则它们会被忽略。

dojo.declare(
　　"foo",
　　null,
　　{
　　// summary: Phew, this sure is relaxing, Frylock.
　　　　// description:
　　　　//　Thousands of years ago, before the dawn of
　　　　//　man as we knew him, there was Sir Santa of Claus: an
　　　　//　ape-like creature making crude and pointless toys out
　　　　//　of dino-bones, hurling them at chimp-like creatures with
　　　　//　crinkled hands regardless of how they behaved the
　　　　//　previous year.
　　　　// returns: Unless Carl pays tribute to the Elfin Elders in space.
}
);