DojoJavascript编程规范规范自己的JavaScript书写
前言
良好的JavaScript书写习惯的优点不言而喻,今天彬Go向大家推荐DojoJavascript编程规范,相当不错的Javascript编程风格规范,建议大家可以借鉴一下此规范编写Javascript。感谢i.feelinglucky的翻译。
序
Anyviolationtothisguideisallowedifitenhancesreadability.
所有的代码都要变成可供他人容易阅读的。
快读参考
核心API请使用下面的风格:
命名规范
1.变量名称必须为小写字母。
2.类的命名使用骆驼命名规则,例如:
Account,EventHandler
3.常量必须在对象(类)或者枚举变量的前部声明。枚举变量的命名必须要有实际的意义,并且其成员必须使用骆驼命名规则或使用大写:
varNodeTypes={
Element:1,
DOCUMENT:2
}
4.简写单词不能使用大写名称作为变量名:
getInnerHtml(),getXml(),XmlDocument
5.方法的命令必须为动词或者是动词短语:
obj.getSomeValue()
6.公有类的命名必须使用混合名称(mixedCase)命名。
7.CSS变量的命名必须使用其对应的相同的公共类变量。
8.私有类的变量属性成员必须使用混合名称(mixedCase)命名,并前面下下划线(_)。例如:
varMyClass=function(){
var_buffer;
this.doSomething=function(){
};
}
9.变量如果设置为私有,则前面必须添加下划线。
this._somePrivateVariable=statement;
10.通用的变量必须使用与其名字一致的类型名称:
setTopic(topic)//变量topic为Topic类型的变量
11.所有的变量名必须使用英文名称。
12.变量如有较广的作用域(largescope),必须使用全局变量;此时可以设计成一个类的成员。相对的如作用域较小或为私有变量则使用简洁的单词命名。
13.如果变量有其隐含的返回值,则避免使用其相似的方法:
getHandler();//避免使用getEventHandler()
14.公有变量必须清楚的表达其自身的属性,避免字义含糊不清,例如:
MouseEventHandler
,而非MseEvtHdlr。
请再次注意这条规定,这样做得的好处是非常明显的。它能明确的表达表达式所定义的含义。例如:
dojo.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),请加添如下的一行使我们的代码更容易阅读:
//vim:ts=4:noet:tw=0:
译注:老外用VIM编辑器比较多,此条可以选择遵循。
代码折叠必须看起来是完成并且是合乎逻辑的:
varo=someObject.get( 注:表达式的缩进与变量声明应为一致的。 变量 布局 块 普通代码段应该看起来如下: IF语句应该看起来像这样: FOR语句应该看起来像这样: WHILE语句应该看起来像这样: DO…WHILE语句应该看起来像这样: SWITCH语句应该看起来像这样: TRY…CATCH语句应该看起来像这样: 单行的IF?ELSE,WHILE或者FOR语句也必须加入括号,不过他们可以这样写: 空白 注释 文档 下面提供了一些基本的函数或者对象的描述方法: 总结(summary):简短的表述此函数或者对象实现的目的 对象函数信息 没有返回值描述 函数的声明 在有的情况下,对于函数的调用和声明是隐义(invisible)的。在这种情况下,我们没有办法在函数中加入说明等(供程序调用)。如果您遭遇了这种情况,您可以使用一个类来封装函数。 注:此此方法只能在函数没有初始化的参数情况下。如过不是,则它们会被忽略。 <h3>参数</h3> 变量 由于实例变量、原型变量和外部变量的声明是一致的,所以有很多的方法声明、修改变量。具体的如何定义和定位应在变量最先出现的位置指明变量的名称、类型、作用域等信息。 对象中的变量注释 应使用和对象值和方法一致的标注方式,比如在他们声明的时候: 返回值 因为函数可以同时返回多个不同(类型)的值,所以应每个返回值之后加入返回类型的注释。注释在行内注释即可,如果所有的返回值为同一类型,则指明返回的类型;如为多个不同的返回值,则标注返回类型为”mixed”。 伪代码(有待讨论) 有时候您需要在函数或者类中添加对于此函数和类的功能性流程描述。如果您打算这样做,您可以使用/*========(=字符最好出现5次或者更多),这样做的好处就是可以不用将这些东西加入代码(译注:原作者的意思可能为代码管理系统)。 这样看起来在/*=====和=====*/会有非常长的一段注释,等待功能调整完毕以后就可以考虑是否删除。 function(/*module.pseudo.kwArgs*/kwArgs){ 原文链接:http://dojotoolkit.org/developer/StyleGuide
varsomeExpression=Expression1
+Expression2
+Expression3;
Expression1,
Expression2,
Expression3
);
注:函数的参数应采用明确的缩进,缩进规则与其他块保持一致。
while(!isDone){
doSomething();
isDone=moreToDo();
}
if(someCondition){
statements;
}elseif(someOtherCondition){
statements;
}else{
statements;
}
for(initialization;condition;update){
statements;
}
while(!isDone){
doSomething();
isDone=moreToDo();
}
do{
statements;
}while(condition);
switch(condition){
caseABC:
statements;
//fallthrough
caseDEF:
statements;
break;
default:
statements;
break;
}
try{
statements;
}catch(ex){
statements;
}finally{
statements;
}
if(condition){statement;}
while(condition){statement;}
for(intialization;condition;update){statement;}
描述(description):对于此函数或者类的简短的描述
返回(return):描述此函数返回什么(并不包括返回类型)
基本函数信息
function(){
//summary:SoonwewillhaveenoughtreasuretoruleallofNewJersey.
//description:Orwecouldjustgetanewroomate.
//Look,yougofindhim.Hedon"tyellatyou.
//AllIevertrytodoismakehimsmileandsingaround
//himanddancearoundhimandhejustlaysintome.
//Hetoldmetogetinthefreezer"causetherewasacarnivalinthere.
//returns:Look,aBananaramatape!
}
{
//summary:Dingle,engagetherainbowmachine!
//description:
//Tellyouwhat,IwishIwas--ohmyg--thatbeam,
//cominguplikethat,thespeed,youmightwannaadjustthat.
//Itreallydidanumberonmyback,there.Imean,andIdon"t
//wannasaywhiplash,justyet,causethat"salittletoofar,
//but,you"reinsured,right?
}
dojo.declare(
"foo",
null,
{
//summary:Phew,thissureisrelaxing,Frylock.
//description:
//Thousandsofyearsago,beforethedawnof
//manasweknewhim,therewasSirSantaofClaus:an
//ape-likecreaturemakingcrudeandpointlesstoysout
//ofdino-bones,hurlingthematchimp-likecreatureswith
//crinkledhandsregardlessofhowtheybehavedthe
//previousyear.
//returns:UnlessCarlpaystributetotheElfinEldersinspace.
}
);
<ol>
<li>简单类型
简单的类型的参数可以直接在函数参数定义中注释说明。
[cclang="javascript"]function(/*String*/foo,/*int*/bar)...
可变类型参数
下面是几个修饰符供参考:
?可选参数
…说面参数范围不确定
数组
function(/*String?*/foo,/*int...*/bar,/*String[]*/baz)...
全局参数描述
如果你想增加一个描述,你可以将它们移至初始化块。
基本信息格式为:*关键字*描述字段(*key*Descriptivesentence)
参数和变量的格式为:*关键字*~*类型*~描述字段(*key*~*type*~Descriptivesentence)
注:*关键字*和~*类型*~可以使用任何字母和数字表述。
function(foo,bar){
//foo:String
//usedforbeingthefirstparameter
//bar:int
//usedforbeingthesecondparameter
}
functionfoo(){
//myString:String
//times:int
//HowmanytimestoprintmyString
//separator:String
//WhattoprintoutinbetweenmyString*
this.myString="placeholdertext";
this.times=5;
}
foo.prototype.setString=function(myString){
this.myString=myString;
}
foo.prototype.toString=function(){
for(inti=0;i<this.times;i++){
dojo.debug(this.myString);
dojo.debug(foo.separator);
}
}
foo.separator="=====";
{
//key:String
//Asimplevalue
key:"value",
//key2:String
//Anothersimplevalue
}
function(){
if(arguments.length){
return"Youpassedargument(s)";//String
}else{
returnfalse;//Boolean
}
}
/*=====
module.pseudo.kwArgs={
//url:String
//Thelocationofthefile
url:"",
//mimeType:String
//text/html,text/xml,etc
mimeType:""
}
=====*/
dojo.debug(kwArgs.url);
dojo.debug(kwArgs.mimeType);
}
翻译(Translatedby):i.feelinglucky{at}gmail.comfromhttp://www.gracecode.com相关文章