Any violation to this guide is allowed if it enhances readability.
所有的代码都要变成可供他人容易阅读的。
核心 API 请使用下面的风格:
结构 | 规则 | 注释 |
模块 | 小写 | 不要使用多重语义(Never multiple words) |
类 | 骆驼 | |
公有方法 | 混合 | 其他的外部调用也可以使用 lower_case(),这样的风格 |
公有变量 | 混合 | |
常量 | 骆驼 或 大写 |
下面的虽然不是必要的,但建议使用:
结构 | 规则 |
私有方法 | 混合,例子:_mixedCase |
私有变量 | 混合,例子:_mixedCase |
方法(method)参数 | 混合,例子:_mixedCase, mixedCase |
本地(local)变量 | 混合,例子:_mixedCase, mixedCase |
1.变量名称 必须为 小写字母。
2.类的命名使用骆驼命名规则,例如:
1
|
Account
, EventHandler
|
3.常量 必须 在对象(类)或者枚举变量的前部声明。枚举变量的命名必须要有实际的意义,并且其成员 必须 使用骆驼命名规则或使用大写:
1
2 3 4 |
var NodeTypes
=
{
Element : 1 , DOCUMENT : 2 } |
4.简写单词 不能使用 大写名称作为变量名:
1
|
getInnerHtml
(
)
, getXml
(
)
, XmlDocument
|
5.方法的命令 必须 为动词或者是动词短语:
1
|
obj.
getSomeValue
(
)
|
6.公有类的命名 必须 使用混合名称(mixedCase)命名。
7.CSS 变量的命名 必须 使用其对应的相同的公共类变量。
8.私有类的变量属性成员 必须 使用混合名称(mixedCase)命名,并前面下下划线(_)。例如:
1
2 3 4 5 |
var MyClass
=
function
(
)
{
var _buffer ; this. doSomething = function ( ) { } ; } |
9.变量如果设置为私有,则前面 必须 添加下划线。
1
|
this._somePrivateVariable
= statement
;
|
10.通用的变量 必须 使用与其名字一致的类型名称:
1
|
setTopic
(topic
)
// 变量 topic 为 Topic 类型的变量
|
11.所有的变量名 必须 使用英文名称。
12.变量如有较广的作用域(large scope),必须使用全局变量;此时可以设计成一个类的成员。相对的如作用域较小或为私有变量则使用简洁的单词命名。
13.如果变量有其隐含的返回值,则避免使用其相似的方法:
1
|
getHandler
(
)
;
// 避免使用 getEventHandler()
|
14.公有变量必须清楚的表达其自身的属性,避免字义含糊不清,例如:
1
|
MouseEventHandler
|
,而非 MseEvtHdlr。
请再次注意这条规定,这样做得的好处是非常明显的。它能明确的表达表达式所定义的含义。例如:
1
|
dojo.
events.
mouse.
Handler
// 而非 dojo.events.mouse.MouseEventHandler
|
15.类/构造函数 可以使用 扩展其基类的名称命名,这样可以正确、迅速的找到其基类的名称:
EventHandler
UIEventHandler
MouseEventHandler
基类可以在明确描述其属性的前提下,缩减其命名:
MouseEventHandler as opposed to MouseUIEventHandler.
缩进请使用 4 个空白符的制表位。
如果您的编辑器支持 文件标签_(file tags),请加添如下的一行使我们的代码更容易阅读:
1
|
// vim:ts=4:noet:tw=0:
|
译注:老外用 VIM 编辑器比较多,此条可以选择遵循。
代码折叠必须看起来是完成并且是合乎逻辑的:
1
2 3 4 5 6 7 8 9 |
var someExpression
= Expression1
+ Expression2 + Expression3 ; var o = someObject. get ( Expression1 , Expression2 , Expression3 ) ; |
注:表达式的缩进与变量声明应为一致的。
注:函数的参数应采用明确的缩进,缩进规则与其他块保持一致。
1
2 3 4 |
while
(
!isDone
)
{
doSomething ( ) ; isDone = moreToDo ( ) ; } |
1
2 3 4 5 6 7 |
if
(someCondition
)
{
statements ; } else if (someOtherCondition ) { statements ; } else { statements ; } |
1
2 3 |
for
(initialization
; condition
; update
)
{
statements ; } |
1
2 3 4 |
while
(
!isDone
)
{
doSomething ( ) ; isDone = moreToDo ( ) ; } |
1
2 3 |
do
{
statements ; } while (condition ) ; |
1
2 3 4 5 6 7 8 9 10 11 |
switch
(condition
)
{
case ABC : statements ; // fallthrough case DEF : statements ; break ; default : statements ; break ; } |
1
2 3 4 5 6 7 |
try
{
statements ; } catch (ex ) { statements ; } finally { statements ; } |
1
2 3 |
if
(condition
)
{ statement
;
}
while (condition ) { statement ; } for (intialization ; condition ; update ) { statement ; } |
下面提供了一些基本的函数或者对象的描述方法:
1
2 3 4 5 6 7 8 9 |
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! } |
没有返回值描述
1
2 3 4 5 6 7 8 9 |
{
// 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)的。在这种情况下,我们没有办法在函数中加入说明等(供程序调用)。如果您遭遇了这种情况,您可以使用一个类来封装函数。
注:此此方法只能在函数没有初始化的参数情况下。如过不是,则它们会被忽略。
1
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
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. } ) ; <h3 >参数 </h3 > <ol > <li >简单类型 简单的类型的参数可以直接在函数参数定义中注释说明。 [cc lang = "javascript" ] function ( /*String*/ foo , /*int*/ bar )... |
1
|
function
(
/*String?*/ foo
,
/*int...*/ bar
,
/*String[]*/ baz
)...
|
基本信息格式为: *关键字* 描述字段 ( *key* Descriptive sentence)
参数和变量的格式为: *关键字* ~*类型*~ 描述字段 ( *key* ~*type*~ Descriptive sentence)
注: *关键字* 和 ~*类型*~ 可以使用任何字母和数字表述。
1
2 3 4 5 6 |
function
(foo
, bar
)
{
// foo: String // used for being the first parameter // bar: int // used for being the second parameter } |
由于实例变量、原型变量和外部变量的声明是一致的,所以有很多的方法声明、修改变量。具体的如何定义和定位应在变量最先出现的位置指明变量的名称、类型、作用域等信息。
1
2 3 4 5 6 7 8 9 |
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 ; } |
1
2 3 |
foo.
prototype.
setString
=
function
(myString
)
{
this. myString = myString ; } |
1
2 3 4 5 6 7 |
foo.
prototype.
toString
=
function
(
)
{
for (int i = 0 ; i < this. times ; i ++ ) { dojo. debug ( this. myString ) ; dojo. debug (foo. separator ) ; } } foo. separator = "=====" ; |
应使用和对象值和方法一致的标注方式,比如在他们声明的时候:
1
2 3 4 5 6 7 |
{
// key: String // A simple value key : "value" , // key2: String // Another simple value } |
因为函数可以同时返回多个不同(类型)的值,所以应每个返回值之后加入返回类型的注释。注释在行内注释即可,如果所有的返回值为同一类型,则指明返回的类型;如为多个不同的返回值,则标注返回类型为”mixed”。
1
2 3 4 5 6 7 |
function
(
)
{
if (arguments. length ) { return "You passed argument(s)" ; // String } else { return false ; // Boolean } } |
有时候您需要在函数或者类中添加对于此函数和类的功能性流程描述。如果您打算这样做,您可以使用 /*======== (= 字符最好出现 5 次或者更多),这样做的好处就是可以不用将这些东西加入代码(译注:原作者的意思可能为代码管理系统)。
这样看起来在 /*===== 和 =====*/ 会有非常长的一段注释,等待功能调整完毕以后就可以考虑是否删除。
1
2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
/*===== module.pseudo.kwArgs = { // url: String // The location of the file url: "", // mimeType: String // text/html, text/xml, etc mimeType: "" } =====*/ function ( /*module.pseudo.kwArgs*/ kwArgs ) { dojo. debug (kwArgs. url ) ; dojo. debug (kwArgs. mimeType ) ; } |
原文链接: http://dojotoolkit.org/developer/StyleGuide
翻译(Translated by):i.feelinglucky{at}gmail.com from http://www.gracecode.com