Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
dev:client_coding:coding_guidelines [2014/04/17 02:30] – [Additional notes] dstillman | dev:client_coding:coding_guidelines [2017/11/27 05:18] (current) – Remove Zotero 5 warning bwiernik | ||
---|---|---|---|
Line 3: | Line 3: | ||
**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 | ||
Line 12: | Line 12: | ||
- | ====== Braces | + | ===== Braces ===== |
Braces should conform to [[http:// | Braces should conform to [[http:// | ||
Line 38: | Line 38: | ||
</ | </ | ||
- | Braces must **always** be used, even if the enclosed block contains a single line. | + | Braces must **always** be used for multi-line conditionals, even if the enclosed block contains a single line. |
Bad: | Bad: | ||
Line 52: | Line 52: | ||
} | } | ||
</ | </ | ||
- | ====== 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 98: | Line 98: | ||
+ | ===== 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 123: | Line 155: | ||
return total; | return total; | ||
} | } | ||
- | </ | ||
- | * Functions should be commented using JSDoc syntax: | ||
- | <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 = ' | ||
</ | </ | ||
* Semicolons should be used at the end of lines, including after anonymous functions: | * Semicolons should be used at the end of lines, including after anonymous functions: |