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)

• ANY DISPLAY OF TEXT INPUT MUST BE TESTED FOR PROPER ESCAPING. If this isn't tested, we don't know that we're safe against HTML injections.

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.

• Please use the W3C markup validation service to check what you write, and to check what the DOM looks like after AJAX inserts new elements.

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