This is an old revision of the document!


JavaScript code in Zotero should conform to the following coding and style guidelines. We encourage Zotero plugin writers to follow these guidelines as well for consistency and possible future integration of code into the Zotero codebase.

Note: Not all current code in Zotero conforms to these guidelines. While existing code generally should not be modified for the sole purpose of conforming, new code or modifications to existing code should follow these guidelines.

Basic style

  • Indent using tabs (width 4), not spaces
  • Lines should generally be kept to 80 characters, except where doing so would seriously decrease readability
  • Objects should be CamelCased and namespaced (Zotero.FooBar within the Zotero XPCOM object, ZoteroFooBar without)
  • Functions and variables should be lowercase (Zotero.Date.sqlToDate(), var foo = true;)
  • Code should comply with JavaScript strict mode (javascript.options.strict in about:config): variables should be initialized before using, etc.

Braces

Braces should conform to K&R style:

function abc() {
    ...
}
 
if (abc == 'def') {
    ...
}

Braces must always be used, even if the enclosed block contains a single line.

Bad:

if (!_initialized)
   init();

Good:

if (!_initialized) {
   init();
}

Public/privileged/private/static methods and members

For an explanation of the difference between public, privileged and private methods and members, please see Douglas Crockford's Private Members in JavaScript.

  • For objects that will be instantiated multiple times, public methods (defined using prototype outside the constructor) should be used rather than privileged methods (defined using this within) for memory and performance reasons:
Zotero.Item = function() {
    ...
}
 
Zotero.Item.prototype.numCreators = function () {
    ...
}
  • Singleton objects should use privileged methods:
Zotero.Date = new function() {
    this.sqlToDate = sqlToDate(sqlDate, isUTC) {
        ...
    }
}
  • Private methods and members (including those that are actually public or privileged for technical reasons but that should be considered private) should be prefixed with an underscore (e.g. var _initialized = false;, Zotero.Item.prototype._loadItemData = function() {…})
  • Related static functions should be placed in a wrapper object using a singleton or object literal notation:
Zotero.FooBar = new function() {
     this.getFooObjects = function () {
          ...
     }
     ...
};

or

Zotero.FooBar = {
     getFooObjects: function () {
          ...
     },
     ...
};

Additional notes

  • Variables should be defined in the smallest scope possible:

Bad:

function sum(num) {
    total = 0; // total is global!
    for (i=0; i<num; i++) { // i is global!
        total += i;
    }
    return total;
}

Good:

function sum(num) {
    var total = 0;
    for (var i=0; i<num; i++) {
        total += i;
    }
    return total;
}
  • Functions should be commented:
/*
 * Does something or other
 *
 * Returns array of ids
 */
function myFunction() {
   ...
}
  • Semicolons should be used at the end of lines, including after anonymous functions:
var func = function () {
    ...
};
  • Abbreviations and acronyms should remain capitalized in names: getID(), generateHTML()
  • Global constants should be placed in the ZOTERO_CONFIG array in zotero.js and capitalized
  • Debugging messages should use the Zotero.debug(message, level) function. level is optional and defaults to 3. Error messages (i.e. things that should never happen and that can't be handled gracefully) should be thrown rather than passed to debug().
  • All user-viewable text should be put in the en-US locale rather than embedded directly into the code, for localization and maintenance purposes.

Other issues

For issues not specified here, Zotero code should generally follow the Dojo Style Guide from the Dojo project.

dev/client_coding/coding_guidelines.1320346908.txt.gz · Last modified: 2011/11/03 15:01 by dstillman