Diff for "JavaScriptReviewNotes"

Not logged in - Log In / Register

Differences between revisions 15 and 16
Revision 15 as of 2009-03-06 20:26:37
Size: 3642
Editor: mars
Comment:
Revision 16 as of 2009-03-06 20:31:53
Size: 3661
Editor: mars
Comment:
Deletions are marked like this. Additions are marked like this.
Line 68: Line 68:
 * The widget unit test suite should leave a clean DOM tree in between tests.
== Tests ==

* The unit test suite should leave a clean DOM tree in between each test case.

JavaScript Review Notes

These are items that any code reviewer should keep in mind when reviewing JavaScript.

CRITICAL

  • ALL JAVASCRIPT FILES MUST BE LINT-FREE

  • NO NEW SCRIPT FILES SHOULD BE PULLED IN BY THE YAHOO COMBO-LOADER (use these instructions to add the scripts properly)

Plain Old JavaScript

  • JavaScript blocks should be indented by 4 spaces.

  • If 3 or more lines of strings are to be joined together, use the [str1, str2, ...].join("") form.

  • 1 and 2 character variable names are to be avoided.
  • Regular expression literals should be avoided.
  • All functions, methods, and object properties should be described with JSDoc comment strings and tags.

  • C++ style comments ("//") should only be used inside function bodies.

  • Per-line var statements are preferred inside function bodies.

  • Function, method, and variable names should follow the PEP 0008 style guide (and no, this is not how the rest of the world does it).

XHTML, CSS, and Styling

  • CSS files should come before JavaScript files in the document head.

  • CSS url() directives should have the file name surrounded by single-quotes: url('spinner.png')

  • XHTML attributes should be surrounded by double-quotes: <input type="text"/>

  • Setting a node's style explicitly with setStyle() should be avoided.

  • To set a node's style, it is preferable to add a CSS class to the node, and let the stylesheet handle the presentation.

Event Handling

  • "e" should be used as the event object variable name in event handlers: function onclick(e) {...}

  • event.halt() should be preferred over event.stopPropagation().

  • Document-wide keypress handlers are dangerous, and should be detached as soon as they are no longer needed.

JavaScript Modules

  • Modules should have a JSDoc string with the @module or @submodule tag.

  • Module names should have the form PROJECTNAME.foo.

  • Module-body content does not have to be indented.
  • Module-wide constants should go at the top of the file, after the module JSDoc string.
  • Multi-line var statements may be used in the module-wide constants block.

Namespaces

  • Modules should declare a PROJECTNAME namespace: Y.namespace("foo");

  • A module's public functions should be attached to the PROJECTNAME namespace object.

  • A module's public functions should not be attached directly to the Y object.

  • It is recommended to have a @namespace tag below the @module tag.

Widgets and Plugins

  • Protected and private method names should be prefixed with an underscore.
  • All protected methods should have the @protected JSDoc tag, even ones like initializer() and renderUI().

  • Event handler method names should be prefixed with _on or _after.

  • Custom events should be documented on the line immediately preceding the line where they are published.
  • All JSDoc strings for attributes should have @attribute, @type, and @default tags.

  • Objects such as Node instances should not be instantiated in the widget's ATTRS hash using value:, use valueFn: instead.

  • All Widgets should have a functional example page.
  • (Not implemented) Widget example pages should follow the Example page Template.

Tests

  • The unit test suite should leave a clean DOM tree in between each test case.


CategoryJavaScript

JavaScriptReviewNotes (last edited 2014-11-30 20:26:24 by blr)