Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dev:client_coding:coding_guidelines [2011/11/03 15:15] – [Public/privileged/private/static methods and members] dstillmandev: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
-  * 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 (''Zotero.FooBar'' within the [[dev/client_coding/javascript_api#the_zotero_object|Zotero XPCOM object]], ''ZoteroFooBar'' without)   * Objects should be CamelCased and namespaced (''Zotero.FooBar'' within the [[dev/client_coding/javascript_api#the_zotero_object|Zotero XPCOM object]], ''ZoteroFooBar'' without)
   * Functions and variables should be lowercase (''Zotero.Date.sqlToDate()'', ''var foo = true;'')   * 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.+  * Code should comply with JavaScript strict mode, with %%"use strict";%% at the top of files: variables should be initialized before using, etc.
  
  
-====== Braces ======+===== Braces =====
  
-Braces should conform to [[http://en.wikipedia.org/wiki/Indent_style#K.26R_style|K&R style]]:+Braces should conform to [[http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS|1TBS variant of the K&R style]]:
  
 <code javascript> <code javascript>
Line 26: Line 26:
 </code> </code>
  
-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) { 
 +</code> 
 + 
 +Good: 
 +<code javascript> 
 +if (foo) { 
 +</code> 
 + 
 +Braces must **always** be used for multi-line conditionals, even if the enclosed block contains a single line.
  
 Bad: Bad:
Line 40: Line 52:
 } }
 </code> </code>
- +===== Public/privileged/private/static methods and members =====
- +
- +
-====== 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 [[http://javascript.crockford.com/private.html|Private Members in JavaScript]].// //For an explanation of the difference between public, privileged and private methods and members, please see Douglas Crockford's [[http://javascript.crockford.com/private.html|Private Members in JavaScript]].//
Line 89: 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, optionalValue) { 
 +   ... 
 +} 
 +</code> 
 + 
 + 
 +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 = 'bar'; 
 +</code> 
 + 
 +Good: 
 +<code javascript> 
 +// This is a comment 
 +var foo = 'bar'; 
 +</code> 
 + 
 + 
 + 
 +===== Additional notes =====
  
   * Variables should be defined in the smallest scope possible:   * Variables should be defined in the smallest scope possible:
Line 109: Line 150:
 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;
-} 
-</code> 
-  * Functions should be commented: 
-<code javascript> 
-/* 
- * Does something or other 
- * 
- * Returns array of ids 
- */ 
-function myFunction() { 
-   ... 
 } }
 </code> </code>
Line 129: Line 159:
  
 <code javascript> <code javascript>
-var func = function () { +var func = function (bar) { 
-    ...+    var foo = bar;
 }; };
 </code> </code>
Line 136: Line 166:
   * Global constants should be placed in the ''ZOTERO_CONFIG'' array in zotero.js and capitalized   * 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()''.   * 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()''.
 +  * When throwing an error, use ''throw new Error()'' instead of throwing a string (which doesn't generate a stack trace)
   * 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.
  
  
  
dev/client_coding/coding_guidelines.1320347709.txt.gz · Last modified: 2011/11/03 15:15 by dstillman