Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
dev:client_coding:coding_guidelines [2011/11/03 15:01] – [Public/privileged/private/static methods and members] dstillman | dev:client_coding:coding_guidelines [2017/11/12 19:53] – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | < | ||
+ | in the process of updating the documentation for | ||
+ | <a href=" | ||
+ | may be outdated in the meantime. Thanks for your understanding.</ | ||
+ | |||
+ | |||
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. | 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. | **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 ===== | + | ===== Basic style ==== |
* Indent using tabs (width 4), not spaces | * Indent using tabs (width 4), not spaces | ||
- | * Lines should generally be kept to 80 characters, except where doing so would seriously decrease readability | + | * Lines should generally be kept to 100 characters, except where doing so would seriously decrease readability |
* Objects should be CamelCased and namespaced ('' | * Objects should be CamelCased and namespaced ('' | ||
* Functions and variables should be lowercase ('' | * Functions and variables should be lowercase ('' | ||
- | * Code should comply with JavaScript strict mode (javascript.options.strict | + | * Code should comply with JavaScript strict mode, with %%" |
- | ====== Braces | + | ===== Braces ===== |
- | Braces should conform to [[http:// | + | Braces should conform to [[http:// |
<code javascript> | <code javascript> | ||
Line 26: | Line 32: | ||
</ | </ | ||
- | Braces must **always** be used, even if the enclosed block contains a single line. | + | Add a space after keywords to distinguish them from function calls: |
+ | |||
+ | Bad: | ||
+ | <code javascript> | ||
+ | if(foo) { | ||
+ | </ | ||
+ | |||
+ | Good: | ||
+ | <code javascript> | ||
+ | if (foo) { | ||
+ | </ | ||
+ | |||
+ | Braces must **always** be used for multi-line conditionals, even if the enclosed block contains a single line. | ||
Bad: | Bad: | ||
Line 40: | Line 58: | ||
} | } | ||
</ | </ | ||
- | + | ===== Public/ | |
- | + | ||
- | + | ||
- | ====== Public/ | + | |
//For an explanation of the difference between public, privileged and private methods and members, please see Douglas Crockford' | //For an explanation of the difference between public, privileged and private methods and members, please see Douglas Crockford' | ||
Line 53: | Line 68: | ||
} | } | ||
- | Zotero.Item.prototype.numCreators = function() { | + | Zotero.Item.prototype.numCreators = function () { |
... | ... | ||
} | } | ||
</ | </ | ||
- | * Singleton objects should use privileged methods: | + | * Singleton objects should use a wrapper object or object notation: |
<code javascript> | <code javascript> | ||
- | Zotero.Date = new function() { | + | Zotero.FooBar |
- | | + | |
+ | var _foo = " | ||
+ | |||
+ | function foo { | ||
... | ... | ||
} | } | ||
- | } | + | |
- | </code> | + | // Public members and methods |
- | * Private | + | |
- | * Related static functions should be placed in a wrapper object using a singleton or object literal notation: | + | getFooObjects: function () { |
- | <code javascript> | + | ... |
- | Zotero.FooBar = new function() | + | } |
- | this.getFooObjects | + | }; |
- | ... | + | }()); |
- | | + | |
- | ... | + | |
- | }; | + | |
</ | </ | ||
Line 80: | Line 95: | ||
<code javascript> | <code javascript> | ||
Zotero.FooBar = { | Zotero.FooBar = { | ||
- | getFooObjects: | + | |
- | ... | + | |
- | | + | }, |
- | | + | ... |
}; | }; | ||
</ | </ | ||
+ | * Private members and pseudo-private members/ | ||
+ | ===== Comments ===== | ||
+ | Functions should be commented using JSDoc syntax: | ||
- | ====== Additional notes ====== | + | <code javascript> |
+ | /** | ||
+ | * Does something or other | ||
+ | * | ||
+ | * @param {string} value - This is a value | ||
+ | * @param {boolean} [optionalValue] - This is an optional value | ||
+ | * @return {number[]} - Array of itemIDs | ||
+ | */ | ||
+ | function myFunction(value, | ||
+ | ... | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | For readability and neatness, add a space after the slashes in line comments, and capitalize the first word: | ||
+ | |||
+ | Bad: | ||
+ | <code javascript> | ||
+ | //this is a comment | ||
+ | var foo = ' | ||
+ | </ | ||
+ | |||
+ | Good: | ||
+ | <code javascript> | ||
+ | // This is a comment | ||
+ | var foo = ' | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ===== Additional notes ===== | ||
* Variables should be defined in the smallest scope possible: | * Variables should be defined in the smallest scope possible: | ||
Line 108: | Line 156: | ||
function sum(num) { | function sum(num) { | ||
var total = 0; | var total = 0; | ||
- | for (var i=0; i<num; i++) { | + | for (let i=0; i<num; i++) { // i is local to the for loop |
total += i; | total += i; | ||
} | } | ||
return total; | return total; | ||
- | } | ||
- | </ | ||
- | * Functions should be commented: | ||
- | <code javascript> | ||
- | /* | ||
- | * Does something or other | ||
- | * | ||
- | * Returns array of ids | ||
- | */ | ||
- | function myFunction() { | ||
- | ... | ||
} | } | ||
</ | </ | ||
Line 128: | Line 165: | ||
<code javascript> | <code javascript> | ||
- | var func = function () { | + | var func = function (bar) { |
- | | + | |
}; | }; | ||
</ | </ | ||
Line 135: | Line 172: | ||
* Global constants should be placed in the '' | * Global constants should be placed in the '' | ||
* Debugging messages should use the '' | * Debugging messages should use the '' | ||
+ | * When throwing an error, use '' | ||
* All user-viewable text should be put in the en-US locale rather than embedded directly into the code, for localization and maintenance purposes. | * 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 [[http:// |