Dojo Style Guide

发布时间:2019-10-11 发布网站:大佬教程
大佬教程收集整理的这篇文章主要介绍了Dojo Style Guide大佬教程大佬觉得挺不错的,现在分享给大家,也给大家做个参考。


This document follows the basic outline of the Java Programming Conventions Guide,a copy of which may be found at .

Widget authors are expected to adhere to this style guide and also to the Dojo Accessibility Design Requirements guidelines.


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

Guidelines in this document are informed by discussions carried out among the Dojo core developers. The most weight has been given to considerations that impact external developer interaction with Dojo code and APIs. Rules such as whitespace placement are of a much lower order importance for Dojo developers,but should be followed in the main in order to improve developer coordination.

Quick Reference

Table of core API naming constructs:

Construct Convention Comment
module lowercase never multiple words
class CamelCase
public method mixedCase whether class or instance method. lower_case() is acceptable only if the particular function is mimicking another API.
public var mixedCase
constant CamelCase or UPPER_CASE

Table of constructs that are not visible in the API,and therefore carry less weight of enforcement.

Construct Convention
private method _mixedCase
private var _mixedCase
method args _mixedCase,mixedCase
local vars _mixedCase,mixedCase

Naming Conventions

  1. When constructing string IDs or ID prefixes in the code,do not use "dojo","dijit" or "dojox" in the names. Because we now allow multiple versions of dojo in a page,it is important you use _scopeName instead (dojo._scopeName,dijit._scopeName,dojox._scopeName).

  2. Names representing modules SHOULD be in all lower case.

  3. Names representing types (classes) MUST be nouns and written using CamelCase capitalization:

  4. Constants SHOULD be placed within a single object created as a holder for constants,emulating an Enum; the enum SHOULD be named appropriately,and members SHOULD be named using either CamelCase or UPPER_CASE capitalization:

    var NodeTypes = {
    Element : 1,
    } ;
  5. Abbreviations and acronyms SHOULD NOT be UPPERCASE when used as a name:

    getInnerHtml ( ),getXml ( ),XmlDocument
  6. Names representing methods SHOULD be verbs or verb phrases:

    obj. getSomeValue ( )
  7. Public class variables MUST be written using mixedCase capitalization.

  8. CSS variable names SHOULD follow the same conventions as public class variables.

  9. Private class variables MAY be written using _mixedCase (with preceding underscore):

    var MyClass = function ( ) {
    var _buffer;
    this . doSomething = function ( ) {
    } ;
  10. Variables that are intended to be private,but are not closure bound,SHOULD be prepended with a "_" (underscore) char:

    this ._somePrivateVariable = statement;

    Note: the above variable also follows the convention for a private variable.

  11. Generic variables SHOULD have the same name as their type:

    setTopic ( topic ) // where topic is of type Topic
  12. All names SHOULD be written in English.

  13. Variables with a large scope SHOULD have globally unambiguous names; ambiguity MAY be distinguished by module membership. Variables with small or private scope MAY have terse names.

  14. The name of the return object is implicit,and SHOULD be avoided in a method name:

    getHandler ( ) ; // NOT getEventHandler()
  15. Public names SHOULD be as clear as necessary and SHOULD avoid unclear shortenings and contractions:

    MouseEventHandler // NOT MseEvtHdlr

    Note that,again,any context that can be determined by module membership SHOULD be used when determining if a variable name is clear. For example,a class that represents a mouse event handler:

    dojo. events . mouse . Handler // NOT
  16. Classes/constructors MAY be named based on their inheritance pattern,with the base class to the right of the name:


    The base class CAN be dropped from a name if it is obviously implicit in the name:

    MouseEventHandler // as opposed to MouseUIEventHandler
  17. Functions that act as both getters and setters depending on the number of arguments are named after nouns. The 'get' and 'set' are implied. For example:
    dojo. attr ( node,"tabIndex" ) ;
    dojo. attr ( node,"tabIndex","-1" ) ;

Specific Naming Conventions

  1. The terms get/set SHOULD NOT used where a field is accessed,unless the variable being accessed is lexically private.

  2. The "is" prefix SHOULD be used for boolean variables and methods. Alternatives include "has","can" and "should"

  3. The term "compute" CAN be used in methods where something is computed.

  4. The term "find" CAN be used in methods where something is looked up.

  5. The terms "initialize" or "init" CAN be used where an object or a concept is established.

  6. UI Control variables SHOULD be suffixed by the control type. Examples: leftComboBox,topScrollPane

  7. Plural form MUST be used to name collections.

  8. A "num" prefix or "count" postfix SHOULD be used for variables representing a number of objects.

  9. Iterator variables SHOULD be called "i","j","k",etc.

  10. Complement names MUST be used for complement entities. Examples: get/set,add/remove,create/destroy,start/stop,insert/delete,begin/end,etc.

  11. Abbreviations in names SHOULD be avoided.

  12. Negated boolean variable names MUST be avoided:

    isNotError,isNotFound are unacceptable.
  13. Exception classes SHOULD be suffixed with "Exception" or "Error" .. FIXME (trt) not sure about this?

  14. Methods returning an object MAY be named after what they return,and methods returning void after what they do.


  1. Class or object-per-file guidelines are not yet determined.

  2. Tabs (set to 4 spaces) SHOULD be used for indentation.

  3. If your editor supports "file tags",please append the appropriate tag at the end of the file to enable others to effortlessly obey the correct indentation guidelines for that file:

    // vim:ts=4:noet:tw=0:
  4. The incompleteness of a split line MUST be made obvious :

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

    Note the indentation for expression continuation is indented relative to the variable name,while indentation for parameters is relative to the method being called.

    Note also the position of the parenthesis in the method call; positioning SHOULD be similar to the use of block notation.


  1. Variables SHOULD be initialized where they are declared and they SHOULD be declared in the smallest scope possible. A null initialization is acceptable.
  2. Variables MUST never have a dual meaning.
  3. Related variables of the same type CAN be declared in a common statement; unrelated variables SHOULD NOT be declared in the same statement.
  4. Variables SHOULD be kept alive for as short a time as possible.
  5. Loops / iterative declarations
    1. Only loop control statements MUST be included in the "for" loop construction.
    2. Loop variables SHOULD be initialized immediately before the loop; loop variables in a "for" statement MAY be initialized in the "for" loop construction.
    3. The use of "do...while" loops is acceptable (unlike in Java).
    4. The use of "break" and "continue" is not discouraged (unlike in Java).
  6. Conditionals
    1. Complex conditional expressions SHOULD be avoided; use temporary boolean variables instead.
    2. The nominal case SHOULD be put in the "if" part and the exception in the "else" part of an "if" statement.
    3. Executable statements in conditionals MUST be avoided.
  7. Miscellaneous
    1. The use of magic numbers in the code SHOULD be avoided; they SHOULD be declared using named "constants" instead.
    2. Floating point constants SHOULD ALWAYS be written with decimal point and at least one decimal.
    3. Floating point constants SHOULD ALWAYS be written with a digit before the decimal point.


  1. Block statements.

    1. Block layout SHOULD BE as illustrated below:
      while ( !isDone ) {
      doSomething ( ) ;
      isDone = moreToDo ( ) ;
    2. if statements SHOULD have the following form:

      if ( someCondition ) {
      } else if ( someOtherCondition ) {
      } else {
    3. for statements SHOULD have the following form:

      for ( initialization; condition; update ) {
    1. while statements SHOULD have the following form:

      while ( !isDone ) {
      doSomething ( ) ;
      isDone = moreToDo ( ) ;
    2. do...while statements SHOULD have the following form:

      do {
      } while ( condition ) ;
    3. switch statements SHOULD have the following form:

      switch ( condition ) {
      case ABC:
      // fallthrough
      case DEF:
      break ;
      default :
      // no break keyword on the last case -- it's redundant
    4. try...catch...finally statements SHOULD have the following form:

      try {
      } catch ( ex ) {
      } finally {
    5. A single statement if-else,while or for MUST NOT be written without brackets,but CAN be written on the same line:

      if ( condition ) { statement; }
      while ( condition ) { statement; }
      for ( intialization; condition; update ) { statement; }
  2. Whitespace

    1. Conventional operators MAY be surrounded by a space (including ternary operators).
    2. The following reserved words SHOULD NOT be followed by a space:
      • break
      • catch
      • continue
      • do
      • else
      • finally
      • for
      • function if anonymous,ex. var foo = function(){};
      • if
      • return
      • switch
      • this
      • try
      • void
      • while
      • with
    3. The following reserved words SHOULD be followed by a space:
      • case
      • default
      • delete
      • function if named,ex. function foo(){};
      • in
      • instanceof
      • new
      • throw
      • typeof
      • var
    4. Commas SHOULD be followed by a space.
    5. Colons MAY be surrounded by a space.
    6. Semi-colons in for statements SHOULD be followed by a space.
    7. Semi-colons SHOULD NOT be preceded by a space.
    8. Function calls and method calls SHOULD NOT be followed by a space. Example: doSomething(someParameter); // NOT doSomething (someParameter)
    9. Logical units within a block SHOULD be separated by one blank line.
    10. Statements MAY be aligned wherever this enhances readability.
  3. Line length

    There's no line length limit in dojo although 120 characters (treating tabs as 4 spaces) is a guideline. In particular code examples embedded into the API documentation may benefit from longer lines,since they start out already indented by 4 or 5 tabs.


    1. Tricky code SHOULD not be commented,but rewritten.
    2. All comments SHOULD be written in English.
    3. Comments SHOULD be indented relative to their position in the code,preceding or to the right of the code in question.
    4. The declaration of collection variables SHOULD be followed by a comment stating the common type of the elements in the collection.
    5. Comments SHOULD be included to explain BLOCKS of code,to explain the point of the following block.
    6. Comments SHOULD NOT be included for every single line of code.


Markup Guidelines

Using a Key

When parsing a comment block,we give the parser a list of "keys" to look for. These include summary,description,and returns,but many comment blocks will also have all of the variables and parameters in the object or function added to this list of keys as well.

Formatting: Each keyword should be on a line by itself,with a space before and a colon after. For variable names there's a type after the colon. The content associated with the keyword is indented by two tabs. For example:

// summary:
// This is the summary for the method.
// It's indented by two tabs.
// foo: Integer
// First argument to this function
// bar: String
// Second argument to this function
// returns:
// A calculated value.

The parser will keep reading content as part of the specified key until it sees a completely blank line,or another keyword.

Although our formatting convention requires that keywords exist on a separate line,if any of these keywords occur at the beginning of a line,the parser will start reading the text following it and save it as part of that key's content. This means that you should be careful about what word you use to start a line. For example,"summary" shouldn't start a line unless the content that follows is the summary.

Using Markdown

The Markdown syntax is used in descriptions and code examples.

In Markdown,to indicate a code block,indent the code block using a single tab. The parser considers the | (pipe) character to indicate the start of a line. You must use | followed by a tab in order to indicate a code block.

In Markdown,to indicate an inline piece of code,surround the code with backticks. eg `<div>`.

General Information

These keys provide descriptions for the function or object:

  • summary: A short statement of the purpose of the function or object. Will be read in plain text (html entity escaped,Markdown only for code escaping)
  • description: A complete description of the function or object. Will appear in place of summary. (uses Markdown)
  • tags: A list of whitespace-separated tags used to indicate how the methods are to be used (see explanations below )
  • this: We assume that this points to a class instance. To clarify,use this key to either set a specific location or the string "namespace" to indicate you're referring to a sibling variable
  • returns: A description of what the function returns (does not include a type,which should appear within the function)
  • example: A writeup of an example. Uses Markdown syntax,so use Markdown syntax to indicate code blocks from any normal text. This key can occur multiple times.


Tags are used to help the documentation tool group things by purpose and to provide other modifers that the language doesn't necessarialy provide (public,private,protected,etc.). Most tags are ad-hoc,which is to say you can invent your own,but several are pre-defined and used throught Dojo code. Most UIs that show documentation understand at least public,callback,and extension.

Methods are assumed to be public,but are considered protected by default if they start with a _prefix. This means that the only time you'd use protected is if you don't want someone to use a function without a _prefix,and the only time you'd use private is if you don't want someone to touch your method at all.

  • protected : The method can be called or overriden by subclasses but should not be accessed (directly) by a user. For example:
    postCreate: function ( ) {
    // summary:
    // Called after a widget's dom has been setup
    // tags:
    // protected
  • private : The method or property is not intended for use by anything other than the class itself. For example:
    _attrToDom: function ( /*String*/ attr,/*String*/ value ) {
    // summary:
    // Reflect a widget attribute (title,tabIndex,duration etc.) to
    // the widget DOM,as specified in attributeMap.
    // tags:
    // private
  • multiple tags : Multiple tags can separated by spaces:
    parse: function ( /*Node*/ node ) {
    // summary:
    // Parse things.
    // tags:
    // protected extension

Method-Specific Tags

  • callback : This method represents a location that a user can connect to (i.e. using dojo.connect ) to receive notification that some event happened,such as a user clicking a button or an animation completing. For example:
    onClick: function ( ) {
    // summary:
    // Called when the user clicks the widget
    // tags:
    // callback
  • extension : Unlike a normal protected method,we mark a function as an extension if the default functionality isn't how we want the method to ultimately behave. This is for things like lifecycle methods (e.g. postCreate ) or methods where a subclass is expected to change some basic default functionality (e.g. buildRendering ). A callback is just a notification that some event happened,an extension is where the widget code is expecting a method to return a value or perform some action. For example,on a calendar:
    isDisabledDate: function ( date ) {
    // summary:
    // Return true if the specified date should be disabled (i.e. grayed
    // out and unclickable)
    // description:
    // Override this method to define special days to gray out,such as
    // weekends or (for an airline) black-out days when discount fares
    // aren't available.
    // tags:
    // extension

General Function Information

Foo = function ( ) {
// summary:
// Soon we will have enough treasure to rule all of New Jersey.
// description:
// Or we could just get a new roommate. 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!
Foo. prototype . onSomething = function ( ) {
// tags: callback

Object Information

Has no description of what it returns
var mcChris = {
// 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?

Function Assembler Information (defineWidget/declare)

If the declaration passes a constructor,the summary and description must be filled in there. If you do not pass a constructor,the comment block can be created in the passed mixins object.

For example:

dojo. declare (
// 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.
) ;


Simple Types

Types should (but don't have to) appear in the main parameter definition block.

For example:

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

Type Modifiers

There are some modifiers you can add after the type:

  • ? means optional
  • ... means the last parameter repeats indefinitely
  • [] means an array
function ( /*String?*/ foo,/*int...*/ bar,/*String[]?*/ baz ) ...

Full Parameter Summaries

If you want to also add a summary,you can do so in the initial comment block. If you've declared a type in the parameter definition,you do not need to redeclare it here.

The format for the general information is: *key *Descriptive sentence

The format for parameters and variables is: *key ~type~* Descriptive sentence

Where *key *and ~*type*~ can be surrounded by any non-alphanumeric characters.

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


Instance variables,prototype variables and external variables can all be defined in the same way. There are many ways that a variable might get assigned to this function,and locating them all inside of the actual function they reference is the best way to not lose track of them,or accidentally comment them multiple times.

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 = "=====" ;

Tagging Variables

Variables can be tagged by placing them in a whitespace-separated format before the type value between [ and ] characters. The tags available for variables are the same as outlined in the main tags,plus a few variable-specific additions:

  • deprecated : In methods,the doc system can search for dojo.deprecated calls. But variables will need specific declarations that they are deprecated.
    // label: [deprecated readonly] String
    // A label thingie
    label: ""
  • const : A widget attribute that can be used for configuration,but can only have its value assigned during initialization. This means that changing this value on a widget instance (even with the attr method) will be a no-op.
    // id: [const] String
    // A unique,opaque ID string that can be assigned by users...
    id: ""
  • readonly : This property is intended to be read and cannot be specified during initialization,or changed after initialization.
    // domNode: [readonly] DomNode
    // This is our visible representation of the widget...
    domNode: null

Variable Comments in an Object

The parser takes the comments in between object values and applies the same rules as if they were in the initial comment block:

// key: String
// A simple value
key: "value",
// key2: String
// Another simple value

Return Value

Because a function can return multiple types,the types should be declared on the same line as the return statement,and the comment must be the last thing on the line. If all the return types are the same,the parser uses that return type. If they're different,the function is considered to return "mixed".

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

Note: The return type should be on the same line as the return statement. The first example is invalid,the second is valid:

function ( ) {
return {
foo: "bar" // return Object
function ( ) {
return { // return Object
foo: "bar"

Documentation-Specific Code

Sometimes objects are constructed in a way that is hard to see from just looking through source. Or we might pass a generic object and want to let the user know what fields they can put in this object. In order to do this,there are two solutions:

Inline Commented-Out Code

There are some instances where you might want an object or function to appear in documentation,but not in Dojo,nor in your build. To do this,start a comment block with /*===== . The number of = can be 5 or more.

The parser simply replaces the /*===== and =====*/ with whitespace at the very start,so you must be very careful about your syntax.

dojo. mixin ( wwwizard,{
// url: String
// The location of the file
url: "",
// mimeType: String
// text/html,text/xml,etc
mimeType: "",

// somethingElse: Boolean
// Put something else here
somethingElse: "eskimo"
} ) ;

Code in a Separate File

Doing this allows us to see syntax highlighting in our text editor,and we can worry less about breaking the syntax of the file that's actually in the code-base during parsing. It's nothing more complicated that writing a normal JS file,with a dojo.provide call.

The trade-off is that it's harder to maintain documentation-only files. It's a good idea to only have one of these per the namespace depth you're at. eg in the same directory that the file you're documenting is. We'll see an example of its use in the next section.

Documenting a kwArg

A lot of Dojo uses keyword-style arguments (kwArg). It's difficult to describe how to use them sometimes. One option is to provide a pseudo-object describing its behavior. So we'll create module/_arg.js and do the following:

dojo. provide ( "module._arg" ) ;
module._arg. myFuncArgs = function ( /*Object*/ kwArgs ) {
// url: String
// Location of the thing to use
// mimeType: String
// Mimetype to return data as
this . url = kwArgs. url ;
this . mimeType = kwArgs. mimeType ;

This describes a real object that mimics the functionality of the generic object you would normally pass,but also provides documentation of what fields it has and what they do.

To associate this object with the originating function,do this:

var myFunc = function ( /*module._arg.myFuncArgs*/ kwArgs ) {
dojo. debug ( kwArgs. url ) ;
dojo. debug ( kwArgs. mimeType ) ;

Since we didn't do a dojo.require on module._arg,it won't get included,but the documentation parser will still provide a link to it,allowing the user to see its functionality. This pseudo object may also be included in-line using the /*===== =====*/ syntax. For an example of how to do this inline,see "dojo.__FadeArgs" pseudo code in dojo/_base/fx.js,used to document dojo.fadeIn() and dojo.fadeOut()

Which Documentation-Specific Syntax To Use

Documenting in another file reduces the chance that your code will break code parsing. It's a good idea from this perspective to use the separate file style as much as possible.

There are many situations where you can't do this,in which case you should use the inline-comment syntax. There is also a fear that people will forget to keep documentation in sync as they add new invisible mixed in fields. If this is a serious concern,you can also use the inline comment syntax.

Using the Doctool locally

If you are a developer who has marked their code up using this syntax and want to test to make sure it is correct,you can run the doctool yourself locally. See INSTALL in util/jsdoc. There is also a tool to quickly view simple parsing found in util/docscripts/_browse.php


The CSS styling basically inherits all the rules from JavaScript,that means "key: value" looks like in JS,etc. Therefore a CSS file might look like this:

.className1 {
color: red;

#idName {
color: blue;

Mainly the rules are:

  • each selector is on a new line
  • the opening curly brace is preceeded by a space
  • the key value pairs have a space after the colon
  • every block is followed by an empty new line

more suggestions

avoid obj["prop"] notation except where necessary -- e.g. prop is a reserved word. use obj.prop instead.

avoid parentheses unless necessary for order of operations or for emphasis.

don't use parentheses for parallelism. e.g.

var foo = (cond) ? a : b;
// or

Whitespace is perhaps more effective (and mandated by the style guide) for making such code readable and gets crunched easily by the build:

if(a == 1 || b == 2)

keywords like 'return' and 'typeof' do not require parenthesis around their operand.

avoid typeof foo == "undefined" construct,except for globals,where it's necessary to avoid a reference error.

// not: 
if(typeof foo == "undefined"){ }
// use instead:
if(foo === undefined){ }

In-line docs

Doesn't documenting in another file defeat the purpose of our doc format which was to inline docs as much as possible,making them easier to read and more likely to be maintained?

Documenting kwargs

I think documenting kwArgs should not be done using seperate code that is useless otherwise.
That is just irritating. I have the possible suggestions:

1) make "kwArgs" a key word,using it as a parameter name the doc tool knows what to do.
Disadvantage: you have to know it has to be named "kwArgs" (but the extra class is even more difficult)

var myFunc = function(/*kwArgs*/ kwArgs){
// url: String
// Location of the thing to use
// mimeType: String
// Mimetype to return data as

2) var myFunc = function(/*kwArgs+*/ kwArgs){
use "kwArgs+" as the doc string

3) var myFunc = function(/*url,mimeType*/ kwArgs){
list all the parameters that kwArgs might have

actually i like the later one best ...



doc updates very helpful

I think the new docs for "kwArgs" make this more clear. Factoring into a separate file makes a lot of sense,IMO,if it's some sort of common type used across many modules. Otherwise,I prefer inlining as much as possible.

Bug references

I suggest we use bug references to document unusual or awkward constructs that require lengthy discussion and might otherwise be misunderstood,but avoid using bug references to document new features or changesets which can be discovered via svn blame.

What about ===

Is there any rule-of-thumb when one should use == versus === (besides the obvious "when you need it").

That is,the following statements do quite different things:
var == null
var === null
var == ""
var === ""
var == 0
var === 0

So in the case of empty (or zero,or null),=== might be required - or == might be required. However,the following statements are equal (I believe)
var == "value"
var === "value"
- or -
var == 1
var === 1

I would suggest that === be reserved ONLY for the required cases above.

Re: ===

I would even say that for the first cases (null,undefined,"") === is required,== might cause bugs!



switch case block

I am using the dojo developer style guide as a reference for our internal projects and I have a remark about switch case block.

It is defined with the case statements vertical-aligned with the switch keyword.
But inside dojo code (core,dijit ...),case are always tabbed from switch keyword.

What's wrong ? Dojo Style Guide or Dojo code ?

this doc,it appears it is

this doc,it appears it is simply losing the formatting. I will find a way to fix.

thanks for pointing that out!


以上是大佬教程为你收集整理的Dojo Style Guide全部内容,希望文章能够帮你解决Dojo Style Guide所遇到的程序开发问题。