Dojo Javascript 編程規(guī)范 規(guī)范自己的JavaScript書寫
前言
良好的JavaScript書寫習(xí)慣的優(yōu)點(diǎn)不言而喻，今天彬Go向大家推薦Dojo Javascript 編程規(guī)范，相當(dāng)不錯(cuò)的 Javascript 編程風(fēng)格規(guī)范，建議大家可以借鑒一下此規(guī)范編寫 Javascript。感謝i.feelinglucky的翻譯。
序
Any violation to this guide is allowed if it enhances readability.
所有的代碼都要變成可供他人容易閱讀的。
快讀參考
核心 API 請(qǐng)使用下面的風(fēng)格：
| 結(jié)構(gòu) | 規(guī)則 | 注釋 |
| 模塊 | 小寫 | 不要使用多重語義（Never multiple words） |
| 類 | 駱駝 | |
| 公有方法 | 混合 | 其他的外部調(diào)用也可以使用 lower_case()，這樣的風(fēng)格 |
| 公有變量 | 混合 | |
| 常量 | 駱駝 或 大寫 |
下面的雖然不是必要的，但建議使用：
| 結(jié)構(gòu) | 規(guī)則 |
| 私有方法 | 混合，例子：_mixedCase |
| 私有變量 | 混合，例子：_mixedCase |
| 方法（method）參數(shù) | 混合，例子：_mixedCase, mixedCase |
| 本地（local）變量 | 混合，例子：_mixedCase, mixedCase |
命名規(guī)范
1.變量名稱 必須為 小寫字母。
2.類的命名使用駱駝命名規(guī)則，例如：
Account, EventHandler
3.常量 必須 在對(duì)象（類）或者枚舉變量的前部聲明。枚舉變量的命名必須要有實(shí)際的意義，并且其成員 必須 使用駱駝命名規(guī)則或使用大寫：
var NodeTypes = {
Element : 1,
DOCUMENT: 2
}
4.簡(jiǎn)寫單詞 不能使用 大寫名稱作為變量名：
getInnerHtml(), getXml(), XmlDocument
5.方法的命令 必須 為動(dòng)詞或者是動(dòng)詞短語：
obj.getSomeValue()
6.公有類的命名 必須 使用混合名稱（mixedCase）命名。
7.CSS 變量的命名 必須 使用其對(duì)應(yīng)的相同的公共類變量。
8.私有類的變量屬性成員 必須 使用混合名稱（mixedCase）命名，并前面下下劃線（_）。例如：
var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}
9.變量如果設(shè)置為私有，則前面 必須 添加下劃線。
this._somePrivateVariable = statement;
10.通用的變量 必須 使用與其名字一致的類型名稱：
setTopic(topic) // 變量 topic 為 Topic 類型的變量
11.所有的變量名 必須 使用英文名稱。
12.變量如有較廣的作用域（large scope），必須使用全局變量；此時(shí)可以設(shè)計(jì)成一個(gè)類的成員。相對(duì)的如作用域較小或?yàn)樗接凶兞縿t使用簡(jiǎn)潔的單詞命名。
13.如果變量有其隱含的返回值，則避免使用其相似的方法：
getHandler(); // 避免使用 getEventHandler()
14.公有變量必須清楚的表達(dá)其自身的屬性，避免字義含糊不清，例如：
MouseEventHandler
，而非 MseEvtHdlr。
請(qǐng)?jiān)俅巫⒁膺@條規(guī)定，這樣做得的好處是非常明顯的。它能明確的表達(dá)表達(dá)式所定義的含義。例如：
dojo.events.mouse.Handler // 而非 dojo.events.mouse.MouseEventHandler
15.類/構(gòu)造函數(shù) 可以使用 擴(kuò)展其基類的名稱命名，這樣可以正確、迅速的找到其基類的名稱：
EventHandler
UIEventHandler
MouseEventHandler
基類可以在明確描述其屬性的前提下，縮減其命名：
MouseEventHandler as opposed to MouseUIEventHandler.
特殊命名規(guī)范
術(shù)語 “get/set” 不要和一個(gè)字段相連，除非它被定義為私有變量。
前面加 “is” 的變量名 應(yīng)該 為布爾值，同理可以為 “has”, “can” 或者 “should”。
術(shù)語 “compute” 作為變量名應(yīng)為已經(jīng)計(jì)算完成的變量。
術(shù)語 “find” 作為變量名應(yīng)為已經(jīng)查找完成的變量。
術(shù)語 “initialize” 或者 “init” 作為變量名應(yīng)為已經(jīng)實(shí)例化（初始化）完成的類或者其他類型的變量。
UI （用戶界面）控制變量應(yīng)在名稱后加控制類型，例如： leftComboBox, TopScrollPane。
復(fù)數(shù)必須有其公共的名稱約定（原文：Plural form MUST be used to name collections）。
帶有 “num” 或者 “count” 開頭的變量名約定為數(shù)字（對(duì)象）。
重復(fù)變量建議使用 “i”, “j”, “k” （依次類推）等名稱的變量。
補(bǔ)充用語必須使用補(bǔ)充詞，例如： get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
能縮寫的名稱盡量使用縮寫。
避免產(chǎn)生歧義的布爾變量名稱，例如：
isNotError, isNotFound 為非法
錯(cuò)誤類建議在變量名稱后加上 “Exception” 或者 “Error”。
方法如果返回一個(gè)類，則應(yīng)該在名稱上說明返回什么；如果是一個(gè)過程，則應(yīng)該說明做了什么。
文件
縮進(jìn)請(qǐng)使用 4 個(gè)空白符的制表位。
如果您的編輯器支持 文件標(biāo)簽_（file tags），請(qǐng)加添如下的一行使我們的代碼更容易閱讀：
// vim:ts=4:noet:tw=0:
譯注：老外用 VIM 編輯器比較多，此條可以選擇遵循。
代碼折疊必須看起來是完成并且是合乎邏輯的：
var someExpression = Expression1
+ Expression2
+ Expression3;
var o = someObject.get(
Expression1,
Expression2,
Expression3
);
注：表達(dá)式的縮進(jìn)與變量聲明應(yīng)為一致的。
注：函數(shù)的參數(shù)應(yīng)采用明確的縮進(jìn)，縮進(jìn)規(guī)則與其他塊保持一致。
變量
- 變量必須在聲明初始化以后才能使用，即便是 NULL 類型。
- 變量不能產(chǎn)生歧義。
- 相關(guān)的變量集應(yīng)該放在同一代碼塊中，非相關(guān)的變量集不應(yīng)該放在同一代碼塊中。
- 變量應(yīng)該盡量保持最小的生存周期。
- 循環(huán)/重復(fù)變量的規(guī)范：
- 只有循環(huán)控制塊的話，則必須使用 FOR 循環(huán)。
- 循環(huán)變量應(yīng)該在循環(huán)開始前就被初始化；如使用 FOR 循環(huán)，則使用 FOR 語句初始化循環(huán)變量。
- “do … while” 語句是被允許的。
- “break” 和 “continue” 語句仍然允許使用（但請(qǐng)注意）。
- 條件表達(dá)式
- 應(yīng)該盡量避免復(fù)雜的條件表達(dá)式，如有必要可以使用臨時(shí)布爾變量。
- The nominal case SHOULD be put in the “if” part and the exception in the “else” part of an “if” statement.
- 應(yīng)避免在條件表達(dá)式中加入塊。
- 雜項(xiàng)
- 盡量避免幻數(shù)（Magic numbers），他們應(yīng)該使用常量來代替。
- 浮點(diǎn)變量必須指明小數(shù)點(diǎn)后一位（即使是 0）。
- 浮點(diǎn)變量必須指明實(shí)部，即使它們?yōu)榱悖ㄊ褂?0. 開頭）。
布局
塊
普通代碼段 應(yīng)該 看起來如下：
while (!isDone){
doSomething();
isDone = moreToDo();
}
IF 語句 應(yīng)該 看起來像這樣：
if (someCondition){
statements;
} else if (someOtherCondition){
statements;
} else {
statements;
}
FOR 語句 應(yīng)該 看起來像這樣：
for (initialization; condition; update){
statements;
}
WHILE 語句 應(yīng)該 看起來像這樣：
while (!isDone) {
doSomething();
isDone = moreToDo();
}
DO … WHILE 語句 應(yīng)該 看起來像這樣：
do {
statements;
} while (condition);
SWITCH 語句 應(yīng)該 看起來像這樣：
switch (condition) {
case ABC:
statements;
// fallthrough
case DEF:
statements;
break;
default:
statements;
break;
}
TRY … CATCH 語句 應(yīng)該 看起來像這樣：
try {
statements;
} catch(ex) {
statements;
} finally {
statements;
}
單行的 IF – ELSE，WHILE 或者 FOR 語句也 必須 加入括號(hào)，不過他們可以這樣寫：
if (condition){ statement; }
while (condition){ statement; }
for (intialization; condition; update){ statement; }
空白
- 操作符 建議 使用空格隔開（包括三元操作符）。
- 下面的關(guān)鍵字 避免使用 空白隔開：
- break
- catch
- continue
- do
- else
- finally
- for
- function （如果為匿名函數(shù)，例如：var foo = function(){}; ）
- if
- return
- switch
- this
- try
- void
- while
- with
- 下面的關(guān)鍵字必須使用空白隔開：
- case
- default
- delete
- function （如果為申明，例如：function foo(){}; ）
- in
- instanceof
- new
- throw
- typeof
- var
- 逗號(hào)（,） 建議 使用空白隔開。
- 冒號(hào)（:） 建議 使用空白隔開。
- 點(diǎn)（.） 在后部 建議 使用空白隔開。
- 點(diǎn)（.） 避免 在前部使用空白。
- 函數(shù)調(diào)用和方法 避免 使用空白，例如： doSomething(someParameter); // 而非 doSomething (someParameter)
- 邏輯塊 之間使用空行。
- 聲明 建議 對(duì)齊使其更容易閱讀。
注釋
- 生澀的代碼就 沒有必要 添加注釋了，首先您需要 重寫 它們。
- 所有的注釋請(qǐng)使用英文。
- 從已解決的方案到未開發(fā)的功能，注釋 必須 與代碼相關(guān)。
- 大量的變量申明后 必須 跟隨一段注釋。
- 注釋需要說明的是代碼段的用處，尤其是接下來的代碼段。
- 注釋 沒有必要 每行都添加。
文檔
下面提供了一些基本的函數(shù)或者對(duì)象的描述方法：
總結(jié)（summary）: 簡(jiǎn)短的表述此函數(shù)或者對(duì)象實(shí)現(xiàn)的目的
描述（description）: 對(duì)于此函數(shù)或者類的簡(jiǎn)短的描述
返回（return）: 描述此函數(shù)返回什么（并不包括返回類型）
基本函數(shù)信息
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!
}
對(duì)象函數(shù)信息
沒有返回值描述
{
// 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?
}
函數(shù)的聲明
在有的情況下，對(duì)于函數(shù)的調(diào)用和聲明是隱義（invisible）的。在這種情況下，我們沒有辦法在函數(shù)中加入說明等（供程序調(diào)用）。如果您遭遇了這種情況，您可以使用一個(gè)類來封裝函數(shù)。
注：此此方法只能在函數(shù)沒有初始化的參數(shù)情況下。如過不是，則它們會(huì)被忽略。
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>參數(shù)</h3>
<ol>
<li>簡(jiǎn)單類型
簡(jiǎn)單的類型的參數(shù)可以直接在函數(shù)參數(shù)定義中注釋說明。
[cc lang="javascript"]function(/*String*/ foo, /*int*/ bar)...
可變類型參數(shù)
下面是幾個(gè)修飾符供參考：
? 可選參數(shù)
… 說面參數(shù)范圍不確定
數(shù)組
function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
全局參數(shù)描述
如果你想增加一個(gè)描述，你可以將它們移至初始化塊。
基本信息格式為： *關(guān)鍵字* 描述字段 （ *key* Descriptive sentence）
參數(shù)和變量的格式為： *關(guān)鍵字* ~*類型*~ 描述字段 （ *key* ~*type*~ Descriptive sentence）
注： *關(guān)鍵字* 和 ~*類型*~ 可以使用任何字母和數(shù)字表述。
function (foo, bar) {
// foo: String
// used for being the first parameter
// bar: int
// used for being the second parameter
}
變量
由于實(shí)例變量、原型變量和外部變量的聲明是一致的，所以有很多的方法聲明、修改變量。具體的如何定義和定位應(yīng)在變量最先出現(xiàn)的位置指明變量的名稱、類型、作用域等信息。
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 = "=====";
對(duì)象中的變量注釋
應(yīng)使用和對(duì)象值和方法一致的標(biāo)注方式，比如在他們聲明的時(shí)候：
{
// key: String
// A simple value
key: "value",
// key2: String
// Another simple value
}
返回值
因?yàn)楹瘮?shù)可以同時(shí)返回多個(gè)不同（類型）的值，所以應(yīng)每個(gè)返回值之后加入返回類型的注釋。注釋在行內(nèi)注釋即可，如果所有的返回值為同一類型，則指明返回的類型；如為多個(gè)不同的返回值，則標(biāo)注返回類型為”mixed”。
function() {
if (arguments.length) {
return "You passed argument(s)"; // String
} else {
return false; // Boolean
}
}
偽代碼（有待討論）
有時(shí)候您需要在函數(shù)或者類中添加對(duì)于此函數(shù)和類的功能性流程描述。如果您打算這樣做，您可以使用 /*======== （= 字符最好出現(xiàn) 5 次或者更多），這樣做的好處就是可以不用將這些東西加入代碼（譯注：原作者的意思可能為代碼管理系統(tǒng)）。
這樣看起來在 /*===== 和 =====*/ 會(huì)有非常長(zhǎng)的一段注釋，等待功能調(diào)整完畢以后就可以考慮是否刪除。
/*=====
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
相關(guān)文章
下面小編就為大家?guī)硪黄狫S操作DOM的一些常用方法。小編覺得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2016-05-05
解析JavaScript面向?qū)ο蟾拍钪械腛bject類型與作用域
這篇文章主要介紹了解析JavaScript面向?qū)ο蟾拍钪械囊妙愋团c作用域,文中重點(diǎn)講解了擴(kuò)充函數(shù)運(yùn)行作用域的需要的call和apply方法,朋友可以參考下2016-05-05
在前端開發(fā)中，我們會(huì)嘗試去定一些規(guī)則和約定，來讓項(xiàng)目質(zhì)量更高，更易于維護(hù)。而對(duì)于這些規(guī)則和約定，我們也會(huì)希望它內(nèi)容簡(jiǎn)單，容易理解。下面小編來和大家一起學(xué)習(xí)一下2019-05-05
下面小編就為大家?guī)硪黄仙Ｕ凧avaScript數(shù)組的用法。小編覺得挺不錯(cuò)的，現(xiàn)在就分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2016-06-06
深入理解JS中的Function.prototype.bind()方法
bind 是 ES5 中新增的一個(gè)方法，可以改變函數(shù)內(nèi)部的this指向。這篇文章小編將帶領(lǐng)大家深入理解Javascript中的Function.prototype.bind()方法。有需要的朋友們可以參考借鑒，下面來一起看看吧。2016-10-10
JavaScript學(xué)習(xí)筆記之JS函數(shù)
這篇文章主要簡(jiǎn)單介紹下javascript中函數(shù)的概念以及函數(shù)的參數(shù)、返回值、局部變量、全局變量以及示例分享，是篇非常不錯(cuò)的文章，推薦給大家學(xué)習(xí)下。2015-01-01
有些朋友在實(shí)現(xiàn)異步局部更新數(shù)據(jù)，會(huì)遇到ajax的執(zhí)行問題，本文將對(duì)此進(jìn)行詳細(xì)介紹，需要了解的朋友可以參考下2012-12-12
JavaScript中反正弦函數(shù)Math.asin()的使用簡(jiǎn)介
這篇文章主要介紹了JavaScript中反正弦函數(shù)Math.asin()的使用,是JS入門學(xué)習(xí)中的基礎(chǔ)知識(shí),需要的朋友可以參考下2015-06-06
第一個(gè)JavaScript入門基礎(chǔ) document.write輸出
關(guān)于JavaScript,他是一個(gè)OOSP（面向?qū)ο竽_本語言）他是用來創(chuàng)建動(dòng)態(tài)網(wǎng)站，增強(qiáng)用戶界面的一門技術(shù)。如果你想了解更多關(guān)于JavaScript的信息，請(qǐng)去維基百科查詢。2010-02-02
這篇文章主要介紹了使用JavaScript刷新網(wǎng)頁的方法,是JS通常被用來實(shí)現(xiàn)的最基本的功能之一,需要的朋友可以參考下2015-06-06