Dojo Javascript programming specification

Preface

A pretty good Javascript programming style specification, I suggest you adopt it This specification writes Javascript. Original link: http://dojotoolkit.org/developer/StyleGuide.

Translated by: i.feelinglucky{at}gmail.com from http://www.gracecode.com. Please indicate the source, author and translator for reprinting. Thank you for your cooperation.

The address of this article: http://code.google.com/p/grace/wiki/DojoStyle.

Order

Any violation to this guide is allowed if it enhances readability.

All code must become easy for others to read.

Quick Reading Reference

For the core API, please use the following style:

< tbody>

< tr>

Structure	Rules	Comments
Module	Lowercase	Never multiple words
Class	Camel
Public methods	Mixed	Other external calls You can also use lower_case(), this style
public variables	mixed
constant	camel or uppercase

Below Although it is not necessary, it is recommended to use:

Structure	Rules
Private method	Mixed, example: _mixedCase
Private Variables	Mixed, example: _mixedCase
Method parameters	Mixed, example: _mixedCase, mixedCase
Local (local) variables	Mixed, example: _mixedCase, mixedCase

naming convention

1. variable name must be lowercase letters.
2. Use camel naming rules for class naming, for example:

Account , EventHandler

3. constant must in the object (class ) Or the front declaration of the enumeration variable. The naming of enumeration variables must have practical meaning, and its members must must use camel naming rules or use uppercase:

var NodeTypes = {
 Element : 1,
 DOCUMENT: 2
} 

4. Abbreviated words cannot use capital names as variable names:

getInnerHtml< /span>(), getXml(), XmlDocument

5. The command of the method must be a verb or a verb phrase:

obj.getSomeValue()

6. Public The naming of the class must use the mixed name (mixedCase) to name it.
7. The naming of CSS variables must use the same public class variables corresponding to them.
8. Variable attribute members of private classes must use a mixed name (mixedCase) to name, and precede it with an underscore (_). For example:

var MyClass span> = function span>(){
 var _buffer;
 this< span class="pun">.doSomething =  function(){
 };
}

9. If the variable is set to private, the front Must add an underscore.

this._somePrivateVariable = statement;

10. General variables Must use the type name consistent with its name:

setTopic( topic)  // The variable topic is a Topic type variable

11. All variable names must use English names.
12. If the variable has a wider scope (large scope), global variables must be used; at this time, it can be designed as a member of a class. Relatively, if the scope is small or private variables, use concise word names.
13. If the variable has its implicit return value, avoid using similar methods:

getHandler (); // Avoid using getEventHandler()

14. Public variables must clearly express their own attributes to avoid ambiguity, for example:

MouseEventHandler instead of MseEvtHdlr. 

Please pay attention to this rule again, the benefits of doing so are very obvious. It can clearly express the meaning defined by the expression. For example:

dojo.events< span class="pun">.mouse.Handler // instead of dojo.events.mouse.MouseEventHandler

15. Class/Construction The function can use to extend the name of its base class, so that the name of its base class can be found correctly and quickly:

EventHandler
UIEventHandler
< span class="typ">MouseEventHandler

The base class can be shortened on the premise of clearly describing its properties:

MouseEventHandler as opposed to MouseUIEventHandler.

Special naming convention

1. Terms “get/set” should not be connected to a field unless it is defined as a private variable.
2. The variable name preceded by “is” should be a boolean value. Similarly, it can be “has”, “can” or “should”.
3. The term “compute” as a variable name should be a variable that has been calculated.
4. The term “find” as the variable name should be a variable that has been searched.
5. The term “initialize” or “init” as a variable name should be a class or other type of variable that has been instantiated (initialized).
6. UI (user interface) control variables should add the control type after the name, for example: leftComboBox, TopScrollPane.
7. Plural form MUST be used to name collections (original: Plural form MUST be used to name collections).
8. Variable names beginning with “num” or “count” are by convention numbers (objects).
9. It is recommended to use variables with names such as “i”, “j”, “k” (and so on) for repeated variables.
10. Supplementary terms must use supplementary words, for example: get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
11. Can Try to use abbreviations for abbreviated names.
12. Avoid ambiguous Boolean variable names, for example:

isNotError , isNotFound is illegal

13. It is recommended to add “Exception” after the variable name for the error class “Or “Error”.
14. If the method returns a class, it should state what it returns on the name; if it is a process, it should state what it did.

File

1. Please use 4 blank tabs for indentation.
2. If your editor supports file tags_ (file tags), please add the following to make our code easier to read:

// vim:ts=4:noet:tw=0:

Annotation: Foreigners use VIM editors a lot, this article can choose to follow.

1. Code folding must look complete and logical:

var someExpression = Expression1
 + Expression2
 + Expression3;
 
var o = someObject.get(
 Expression1,
 Expression2,
 Express ion3
);

Note: Expression indentation and variables The statement should be consistent.

Note: The parameters of the function should be clearly indented, and the indentation rules are consistent with other blocks.

Variables

1. Variables must be declared and initialized before they can be used, even if they are of NULL type.
2. Variables must not be ambiguous.
3. Related variable sets should be placed in the same code block, and non-related variable sets should not be placed in the same code block.
4. Variables should try to keep their life cycle to a minimum.
5. The specification of loop/repeat variable:
   1. If only loop control block, FOR loop must be used.
   2. The loop variable should be initialized before the loop starts; if you use a FOR loop, use the FOR statement to initialize the loop variable.
   3. The “do … while” statement is allowed.
   4. The “break” and “continue” statements are still allowed (but please note).
6. Conditional expressions
   1. Complex conditional expressions should be avoided as much as possible, and temporary boolean variables can be used if necessary.
   2. The nominal case SHOULD be put in the “if” part and the exception in the “else” part of an “if” statement.
   3. The conditional expression should be avoided piece.
7. Miscellaneous
   1. Try to avoid magic numbers, they should use constants instead.
   2. Floating point variables must specify one digit after the decimal point (even if it is 0).
   3. Floating point variables must specify the real part, even if they are zero (use 0. at the beginning).

Layout

Block

1. Common code snippet Should Look It looks like this:

while (! isDone){
 doSomething();
 isDone = moreToDo ();
}

2. The IF statement should look like this:

if (someCondition){
 statements;
}< /span> else if< /span> (someOtherCondition){
 statements< /span>;
} else {
 statements;
}

3. The FOR statement should look like this:

for (initialization;< span class="pln"> condition; update){ span>
 statements;
}

4. The WHILE statement should look like this:

while (!isDone)  {
 doSomething();
 isDone = moreToDo span>();
}

< li>DO … WHILE statement should look like this:

do {
 statements; 
} while< /span> (condition) ;

5. The SWITCH statement should look like this:

switch span> (condition) {
case< span class="pln"> ABC:
 statements; 
 // fallthrough
< span class="kwd">case DEF:
 statements ;
 break;
default:< span class="pln">
 statements;
 break;
}

6. TRY … C The ATCH statement should look like this:

try  span>{
 statements;
} catch(ex) {
 statements;
} finally {
 statements;
}

7. Single-line IF-ELSE, WHILE or FOR statements are also required Add parentheses, but they can write like this:

if (condition){ statement;  }
while< /span> (condition) { statement; }
for (intialization; condition; update){ statement; }

Blank

1. Operators recommendation Use spaces to separate them (including ternary operators).
2. The following keywords Avoid using White space separation:
   • break
   • catch
   • continue
   • do
   • else
   • finally
   • for
   • function (If it is an anonymous function, for example: var foo = function( ){}; )
   • if
   • return
   • switch
   • this
   • try

   < li>void

   • while
   • with
3. The following keywords must be separated by whitespace:
   • case
   • default
   • delete
   • function (if it is a declaration, for example: function foo(){}; )
   • in

   li>

   • instanceof
   • new
   • throw
   • typeof
   • var
4. Comma (,) Suggested Use blanks to separate.
5. colon (:) recommendation to use blanks to separate.
6. dot (.) in the back recommendation to use a blank space.
7. Click (.) Avoid use blanks in the front.
8. Function calls and methods Avoid use blanks, for example: doSomething(someParameter); // instead of doSomething (someParameter)
9. Use blank lines between logic blocks.
10. Statement Suggestion Alignment to make it easier to read.

Comments

1. The jerky code is not necessary to add comments, first you need to rewrite They.
2. All comments please use English.
3. From the resolved solution to the undeveloped function, the comment must be related to the code.
4. After a large number of variables are declared, must follow a comment.
5. The comment needs to explain the usefulness of the code segment, especially the following code segment.
6. Comment not necessary Add every line.

Document

The following provides some basic functions or object description methods:

• < strong>summary: a brief description of the purpose of this function or object
• description: a brief description of this function or class< /li>
• return: Describe what this function returns (not including the return type)

Basic function information

function(){
 < span class="com">// 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!
}

Object function information< /h3>

No return value description

{
  // 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 littl e too far,
 // but, you're insured, right?
}

Declaration of function

In some cases, for the function Calls and declarations are invisible. In this case, we have no way to add descriptions and so on in the function (for the program to call). If you encounter this situation, you can use a class to encapsulate the function.

Note: This method can only be used when the function has no initialized parameters. If they are not, they will be ignored.

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
 // < br> // returns: Unless Carl pays tribute to the Elfin Elders in space.
 }
);

Parameters);

Parameters h3>

1. Simple type

Simple type parameters can be commented directly in the function parameter definition.

function(/*String*/ foo, /*int */ bar)...

2. Variable type parameters
   • ? Optional parameters
   • … The scope of the face parameter is uncertain
   • Array

   function(/*String?*/ foo, < span class="com">/*int...*/ bar, /*String[]*/ baz).. .

Here are a few modifiers for reference:

3. Global parameter description

If you want to add A description, you can move them to the initialization block.

The basic information format is: *keyword* description field( *key* Descriptive sentence)

The format of parameters and variables is: *keyword* ~*type*~ description field( *key* ~*type*~ Descriptive sentence)

Note: *Keyword* and ~*Type*~ can use any letters and numbers to express.

function (foo, bar) {
 // foo: String
 // used for being the first parameter
 // bar: int
 // // used for being the second parameter
}

variable

Because the declarations of instance variables, prototype variables and external variables are consistent, there are many ways to declare and modify variables. The specific definition and positioning should indicate the name, type, scope and other information of the variable at the position where the variable first appears.

function foo() span> {
  // myString: String
 // times: int< br> // How many times to print myString
 / / separator: String
 // What to print out in between myString*
 this.myString < span class="pun">= "placeholder text";< /span>
 this.times = 5;
}

foo.prototype.setString = function (myString) {< span class="pln">
 this.myString < /span>= myString; 
}

foo. span>prototype.toString =  function() { 
 for(int i = 0; i < this.times< span class="pun">; i++)  span>{
 dojo.debug(this.myString);
 dojo. span>debug(foo.separator);
 }
}
foo. separator = "=== ==";

对象中的变量注释

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

{
    // key: String
    //          A simple value
    key: "value"< /span>,
    // key2: String
    //          Another simple value
}

返回值

因为函数可以同时返回多个不同（类型）的值，所以应每个返回值之后加入返回类型的注释。注释在行内注释即可，如果所有的返回值为同一类型，则指明返回的类型；如为多个不同的返回值，则标注返回类型为”mixed”。

function() {
        if (arguments.length) {
                return "You passed argument(s)"; // String
        } else {
        return false; // Boolean
    }
}

伪代码（有待讨论）

有时候您需要在函数或者类中添加对于此函数和类的功能性流程描述。如果您打算这样做，您可以使用 /*======== （= 字符最好出现 5 次或者更多），这样做的好处就是可以不用将这些东西加入代码（译注：原作者的意思可能为代码管理系统）。

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

/*=====
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);
}