dojoJS规范.docx

dojoJS规范.docx

《dojoJS规范.docx》由会员分享，可在线阅读，更多相关《dojoJS规范.docx（19页珍藏版）》请在冰豆网上搜索。

dojoJS规范

前言

良好的JavaScript书写习惯的优点不言而喻，今天彬Go向大家推荐DojoJavascript编程规范，相当不错的Javascript编程风格规范，建议大家可以借鉴一下此规范编写Javascript。

感谢i.feelinglucky的翻译。

序

Anyviolationtothisguideisallowedifitenhancesreadability.

所有的代码都要变成可供他人容易阅读的。

快读参考

核心API请使用下面的风格：

结构规则注释

模块小写不要使用多重语义（Nevermultiplewords）

类骆驼

公有方法混合其他的外部调用也可以使用lower_case（），这样的风格

公有变量混合

常量骆驼或大写

下面的虽然不是必要的，但建议使用：

结构规则

私有方法混合，例子：

_mixedCase

私有变量混合，例子：

_mixedCase

方法（method）参数混合，例子：

_mixedCase,mixedCase

本地（local）变量混合，例子：

_mixedCase,mixedCase

命名规范

1.变量名称必须为小写字母。

2.类的命名使用骆驼命名规则，例如：

1Account,EventHandler

3.常量必须在对象（类）或者枚举变量的前部声明。

枚举变量的命名必须要有实际的意义，并且其成员必须使用骆驼命名规则或使用大写：

1

2

3

4varNodeTypes={

Element:

1,

DOCUMENT:

2

}

4.简写单词不能使用大写名称作为变量名：

1getInnerHtml（）,getXml（）,XmlDocument

5.方法的命令必须为动词或者是动词短语：

1obj.getSomeValue（）

6.公有类的命名必须使用混合名称（mixedCase）命名。

7.CSS变量的命名必须使用其对应的相同的公共类变量。

8.私有类的变量属性成员必须使用混合名称（mixedCase）命名，并前面下下划线（_）。

例如：

1

2

3

4

5varMyClass=function（）{

var_buffer;

this.doSomething=function（）{

};

}

9.变量如果设置为私有，则前面必须添加下划线。

1this._somePrivateVariable=statement;

10.通用的变量必须使用与其名字一致的类型名称：

1setTopic（topic）//变量topic为Topic类型的变量

11.所有的变量名必须使用英文名称。

12.变量如有较广的作用域（largescope），必须使用全局变量；此时可以设计成一个类的成员。

相对的如作用域较小或为私有变量则使用简洁的单词命名。

13.如果变量有其隐含的返回值，则避免使用其相似的方法：

1getHandler（）;//避免使用getEventHandler（）

14.公有变量必须清楚的表达其自身的属性，避免字义含糊不清，例如：

1MouseEventHandler

，而非MseEvtHdlr。

　　请再次注意这条规定，这样做得的好处是非常明显的。

它能明确的表达表达式所定义的含义。

例如：

　　　1dojo.events.mouse.Handler//而非dojo.events.mouse.MouseEventHandler

15.类/构造函数可以使用扩展其基类的名称命名，这样可以正确、迅速的找到其基类的名称：

　EventHandler

　UIEventHandler

　MouseEventHandler

　　基类可以在明确描述其属性的前提下，缩减其命名：

　　　MouseEventHandlerasopposedtoMouseUIEventHandler.

特殊命名规范

术语“get/set”不要和一个字段相连，除非它被定义为私有变量。

前面加“is”的变量名应该为布尔值，同理可以为“has”,“can”或者“should”。

术语“compute”作为变量名应为已经计算完成的变量。

术语“find”作为变量名应为已经查找完成的变量。

术语“initialize”或者“init”作为变量名应为已经实例化（初始化）完成的类或者其他类型的变量。

UI（用户界面）控制变量应在名称后加控制类型，例如：

leftComboBox,TopScrollPane。

复数必须有其公共的名称约定（原文：

PluralformMUSTbeusedtonamecollections）。

带有“num”或者“count”开头的变量名约定为数字（对象）。

重复变量建议使用“i”,“j”,“k”（依次类推）等名称的变量。

补充用语必须使用补充词，例如：

get/set,add/remove,create/destroy,start/stop,insert/delete,begin/end,etc.

能缩写的名称尽量使用缩写。

避免产生歧义的布尔变量名称，例如：

　　isNotError,isNotFound为非法

错误类建议在变量名称后加上“Exception”或者“Error”。

方法如果返回一个类，则应该在名称上说明返回什么；如果是一个过程，则应该说明做了什么。

文件

缩进请使用4个空白符的制表位。

如果您的编辑器支持文件标签_（filetags），请加添如下的一行使我们的代码更容易阅读：

1//vim:

ts=4:

noet:

tw=0:

译注：

老外用VIM编辑器比较多，此条可以选择遵循。

代码折叠必须看起来是完成并且是合乎逻辑的：

1

2

3

4

5

6

7

8

9varsomeExpression=Expression1

+Expression2

+Expression3;

varo=someObject.get（

Expression1,

Expression2,

Expression3

）;

注：

表达式的缩进与变量声明应为一致的。

注：

函数的参数应采用明确的缩进，缩进规则与其他块保持一致。

变量

变量必须在声明初始化以后才能使用，即便是NULL类型。

变量不能产生歧义。

相关的变量集应该放在同一代码块中，非相关的变量集不应该放在同一代码块中。

变量应该尽量保持最小的生存周期。

循环/重复变量的规范：

只有循环控制块的话，则必须使用FOR循环。

循环变量应该在循环开始前就被初始化；如使用FOR循环，则使用FOR语句初始化循环变量。

“do…while”语句是被允许的。

“break”和“continue”语句仍然允许使用（但请注意）。

条件表达式

应该尽量避免复杂的条件表达式，如有必要可以使用临时布尔变量。

ThenominalcaseSHOULDbeputinthe“if”partandtheexceptioninthe“else”partofan“if”statement.

应避免在条件表达式中加入块。

杂项

尽量避免幻数（Magicnumbers），他们应该使用常量来代替。

浮点变量必须指明小数点后一位（即使是0）。

浮点变量必须指明实部，即使它们为零（使用0.开头）。

布局

块

普通代码段应该看起来如下：

1

2

3

4while（!

isDone）{

doSomething（）;

isDone=moreToDo（）;

}

IF语句应该看起来像这样：

1

2

3

4

5

6

7if（someCondition）{

statements;

}elseif（someOtherCondition）{

statements;

}else{

statements;

}

FOR语句应该看起来像这样：

1

2

3for（initialization;condition;update）{

statements;

}

WHILE语句应该看起来像这样：

1

2

3

4while（!

isDone）{

doSomething（）;

isDone=moreToDo（）;

}

DO…WHILE语句应该看起来像这样：

1

2

3do{

statements;

}while（condition）;

SWITCH语句应该看起来像这样：

1

2

3

4

5

6

7

8

9

10

11switch（condition）{

caseABC:

statements;

//fallthrough

caseDEF:

statements;

break;

default:

statements;

break;

}

TRY…CATCH语句应该看起来像这样：

1

2

3

4

5

6

7try{

statements;

}catch（ex）{

statements;

}finally{

statements;

}

单行的IF–ELSE，WHILE或者FOR语句也必须加入括号，不过他们可以这样写：

1

2

3if（condition）{statement;}

while（condition）{statement;}

for（intialization;condition;update）{statement;}

空白

操作符建议使用空格隔开（包括三元操作符）。

下面的关键字避免使用空白隔开：

break

catch

continue

do

else

finally

for

function（如果为匿名函数，例如：

varfoo=function（）{};）

if

return

switch

this

try

void

while

with

下面的关键字必须使用空白隔开：

case

default

delete

function（如果为申明，例如：

functionfoo（）{};）

in

instanceof

new

throw

typeof

var

逗号（,）建议使用空白隔开。

冒号（:

）建议使用空白隔开。

点（.）在后部建议使用空白隔开。

点（.）避免在前部使用空白。

函数调用和方法避免使用空白，例如：

doSomething（someParameter）;//而非doSomething（someParameter）

逻辑块之间使用空行。

声明建议对齐使其更容易阅读。

注释

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

所有的注释请使用英文。

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

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

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

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

文档

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

总结（summary）:

简短的表述此函数或者对象实现的目的

描述（description）:

对于此函数或者类的简短的描述

返回（return）:

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

基本函数信息1

2

3

4

5

6

7

8

9function（）{

//summary:

SoonwewillhaveenoughtreasuretoruleallofNewJersey.

//description:

Orwecouldjustgetanewroomate.

//Look,yougofindhim.Hedon'tyellatyou.

//AllIevertrytodoismakehimsmileandsingaround

//himanddancearoundhimandhejustlaysintome.

//Hetoldmetogetinthefreezer'causetherewasacarnivalinthere.

//returns:

Look,aBananaramatape!

}

对象函数信息

没有返回值描述1

2

3

4

5

6

7

8

9{

//summary:

Dingle,engagetherainbowmachine!

//description:

//Tellyouwhat,IwishIwas--ohmyg--thatbeam,

//cominguplikethat,thespeed,youmightwannaadjustthat.

//Itreallydidanumberonmyback,there.Imean,andIdon't

//wannasaywhiplash,justyet,causethat'salittletoofar,

//but,you'reinsured,right?

}

函数的声明

在有的情况下，对于函数的调用和声明是隐义（invisible）的。

在这种情况下，我们没有办法在函数中加入说明等（供程序调用）。

如果您遭遇了这种情况，您可以使用一个类来封装函数。

注：

此此方法只能在函数没有初始化的参数情况下。

如过不是，则它们会被忽略。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22dojo.declare（

"foo",

null,

{

//summary:

Phew,thissureisrelaxing,Frylock.

//description:

//Thousandsofyearsago,beforethedawnof

//manasweknewhim,therewasSirSantaofClaus:

an

//ape-likecreaturemakingcrudeandpointlesstoysout

//ofdino-bones,hurlingthematchimp-likecreatureswith

//crinkledhandsregardlessofhowtheybehavedthe

//previousyear.

//returns:

UnlessCarlpaystributetotheElfinEldersinspace.

}

）;

参数

1. 简单类型

   　　　简单的类型的参数可以直接在函数参数定义中注释说明。

   [cclang="javascript"]function（/*String*/foo,/*int*/bar）...

   可变类型参数

   　　下面是几个修饰符供参考：

   ?

   可选参数

   …说面参数范围不确定

   数组1function（/*String?

   */foo,/*int...*/bar,/*String[]*/baz）...

   全局参数描述

   　如果你想增加一个描述，你可以将它们移至初始化块。

   基本信息格式为：

   *关键字*描述字段（*key*Descriptivesentence）

   参数和变量的格式为：

   *关键字*~*类型*~描述字段（*key*~*type*~Descriptivesentence）

   注：

   *关键字*和~*类型*~可以使用任何字母和数字表述。

   1

   2

   3

   4

   5

   6function（foo,bar）{

   //foo:

   String

   //usedforbeingthefirstparameter

   //bar:

   int

   //usedforbeingthesecondparameter

   }

   变量

   由于实例变量、原型变量和外部变量的声明是一致的，所以有很多的方法声明、修改变量。

   具体的如何定义和定位应在变量最先出现的位置指明变量的名称、类型、作用域等信息。

   1

   2

   3

   4

   5

   6

   7

   8

   9functionfoo（）{

   //myString:

   String

   //times:

   int

   //HowmanytimestoprintmyString

   //separator:

   String

   //WhattoprintoutinbetweenmyString*

   this.myString="placeholdertext";

   this.times=5;

   }

   1

   2

   3foo.prototype.setString=function（myString）{

   this.myString=myString;

   }

   1

   2

   3

   4

   5

   6

   7foo.prototype.toString=function（）{

   for（inti=0;i

   dojo.debug（this.myString）;

   dojo.debug（foo.separator）;

   }

   }

   foo.separator="=====";

   对象中的变量注释

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

   1

   2

   3

   4

   5

   6

   7{

   //key:

   String

   //Asimplevalue

   key:

   "value",

   //key2:

   String

   //Anothersimplevalue

   }

   返回值

   因为函数可以同时返回多个不同（类型）的值，所以应每个返回值之后加入返回类型的注释。

   注释在行内注释即可，如果所有的返回值为同一类型，则指明返回的类型；如为多个不同的返回值，则标注返回类型为”mixed”。

   1

   2

   3

   4

   5

   6

   7function（）{

   if（arguments.length）{

   return"Youpassedargument（s）";//String

   }else{

   returnfalse;//Boolean

   }

   }

   伪代码（有待讨论）

   有时候您需要在函数或者类中添加对于此函数和类的功能性流程描述。

   如果您打算这样做，您可以使用/*========（=字符最好出现5次或者更多），这样做的好处就是可以不用将这些东西加入代码（译注：

   原作者的意思可能为代码管理系统）。

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

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15/*=====

   module.pseudo.kwArgs={

   //url:

   String

   //Thelocationofthefile

   url:

   "",

   //mimeType:

   String

   //text/html,text/xml,etc

   mimeType:

   ""

   }

   =====*/

   function（/*module.pseudo.kwArgs*/kwArgs）{

   dojo.debug（kwArgs.url）;

   dojo.debug（kwArgs.mimeType）;

   }