This document may be superceded by the Y! JavaScript Conventions, should they be published.

Prime Directive

• Planet Yazaar add-ons should look and feel like YUI components.
• Conventions observed in code created for later releases of YUI are preferred to conventions of earlier releases.
• Conventions documented by Douglas Crockford are preferred to conventions observed in YUI code or standard Java conventions.
• Items are tagged (c), (y), or (z) to indicate whether the source of the convention is Crockford, YUI, or Yazaar.

Coding Style

• Observe Crockford's Code Conventions for the JavaScript Programming Language (Read me first!), unless otherwise noted.
• Conventions mentioned in Crockford's videos are also observed unless otherwise noted.
• Exception: A leading underscore may be used to indicate methods intended as private. (y)
• Otherwise, observe typical Java coding conventions, as described by Sun and The Elements of Java Style.
• The Crockford and Java conventions are incorporated by reference. Noted here are exceptions, additions, and clarifications.

HTML tags

• Observe HTML 4.01 Strict, and include TYPE attributes in SCRIPT tags, as it is required by the DTD. (z)
• Place REL and TYPE attributes after the SRC or HREF attributes. (z)
• If a scripts requires a stylesheet, keep the LINK and SCRIPT tags together. (z)
• To improve legibility and coordination with LINK tags, SCRIPT tags should be specified in the HEAD. Inline scripts may be placed in a DIV at the foot of the body. (z)
• Use Yahoo! hosted scripts. Place LINK and SCRIPT tags in HappyTrails order (except reset-font-grids). (z)

<link href="http://yui.yahooapis.com/2.2.2/build/reset-fonts-grids/reset-fonts-grids.css" rel="stylesheet" type="text/css">

<script src="http://www.json.org/json.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/element/element-beta-min.js" type="text/javascript"></script>
<link  href="http://yui.yahooapis.com/2.2.2/build/logger/assets/logger.css" rel="stylesheet" type="text/css" />        
<script src="http://yui.yahooapis.com/2.2.2/build/logger/logger-min.js" type="text/javascript"></script>        
<script src="http://yui.yahooapis.com/2.2.0/build/connection/connection-min.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/animation/animation-min.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/dragdrop/dragdrop-min.js" type="text/javascript" ></script>

<link  href="http://yui.yahooapis.com/2.2.2/build/container/assets/container.css" rel="stylesheet" type="text/css"/>
<script src="http://yui.yahooapis.com/2.2.2/build/container/container-min.js" type="text/javascript"></script>
<link  href="http://yui.yahooapis.com/2.2.2/build/tabview/assets/tabview.css" rel="stylesheet" type="text/css" />
<link  href="http://yui.yahooapis.com/2.2.2/build/tabview/assets/border_tabs.css" rel="stylesheet" type="text/css" />
<script src="http://yui.yahooapis.com/2.2.2/build/tabview/tabview-min.js" type="text/javascript"></script>
<link  href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css" rel="stylesheet">
<script src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js" type="text/javascript"></script> 
<script src="http://yui.yahooapis.com/2.2.2/build/datasource/datasource-beta-min.js" type="text/javascript"></script>        
<link  href="http://yui.yahooapis.com/2.2.2/build/datatable/assets/datatable.css" rel="stylesheet" type="text/css" />

<script src="http://yui.yahooapis.com/2.2.2/build/autocomplete/autocomplete-min.js" type="text/javascript"></script>
<link  href="http://yui.yahooapis.com/2.2.2/build/button/assets/button.css" rel="stylesheet" type="text/css">
<script src="http://yui.yahooapis.com/2.2.2/build/button/button-beta-min.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/slider/slider-min.js" type="text/javascript"></script>
<link  href="http://yui.yahooapis.com/2.2.2/build/calendar/assets/calendar.css" rel="stylesheet" type="text/css">
<script src="http://yui.yahooapis.com/2.2.2/build/calendar/calendar-min.js" type="text/javascript"></script>
<script src="http://yui.yahooapis.com/2.2.2/build/history/history-experimental-min.js" type="text/javascript"></script>

Constants

As in Java, predefined values (or "constants") can be expressed as variables in all UPPER_CASE. JavaScript does not prevent these variables from being changed, and so developers must practice constraint (and observe coding conventions!).

When several related constants or default values are being defined, it can be convenient to group the constants into an object. (y)

YAHOO.widget.Module._EVENT_TYPES = {
    "BEFORE_INIT": "beforeInit",
    "INIT": "init" }

YAHOO.widget.Module._DEFAULT_CONFIG = {
    "VISIBLE": { 
        key: "visible", 
        value: true, 
        validator: YAHOO.lang.isBoolean 
    }

When a constant is being declared for Constructor (or "Class"), assign the constant directly to the Constructor. (y)

YAHOO.widget.DataTable.CLASS_BODY = "yui-dt-body";

When a property is assigned a default value that may be changed by instances of the Constructor, then assign the property to the prototype. (y)

YAHOO.widget.DataTable._nCount = 0;

Variable Type Prefixes

• Variable type prefixes should be applied consistently and conscientiously. (z)

Suffixes

Other Clarifications

• Utilize either "new" Constructors or "object" Constructors as convenient to the circumstances. (c),(y)
• Insert a space after a if or else statement. Do not insert a space between a function name and the parameter list, but insert a space if the function is anonymous. (c)
• if (condition)
• var t = that(something);
• function outer(c, ) {
• method: function () {

File Format

JavaScript files should include a copyright and license header, and documentation comments using JavaDoc style tags. Code may also be organized into a common set of regions. (y)

Copyright/License Header

/*
Copyright (c) 2007, Husted dot Com Inc. All rights reserved.
Portions Copyright (c) 2007, Yahoo!, Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.net/yui/license.txt
*/

• Use your entity for the primary copyright.
• Cite Yahoo! if the code is derived from a YUI class.
• There is not need to cite Yahoo! as a copyright holder if the code is original and merely uses YUI components.

JavaDoc Style Comments

• All code contributions should be fully documented, in the YUI style. (y)
• In general observe the Sun JavaDoc conventions.
• Prefer the YUI tags (as follows).

/**
 * The module object is ....
 * @module 
 * @requires
 * @optional
 * @title
 * @beta
 * @experimental
 */

/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

/**
 * Class is ...
 * @description (deprecated?)
 * @namespace
 * @class
 * @method
 * @property
 * @event
 * @uses
 * @private
 * @public
 * @static
 * @type
 * @constructor
 * @param {type} name Remark
 * @return
*/

• When documenting a field with a default value, the default value may be given in square brackets are part of the documentation comment.

The JsDoc tool can be used with the YUI tags, but not to the same effect as achieved by YUI's internal tool. The JsDoc Toolkit can also be used if certain required tags and include. Other tools and taglets may be used.

Common Code Regions

If code regions are utilized, prefer the common YUI regions. (y)

• Constructor
• DOM events
• Custom events
• Public constants
• Private member variables (properties)
• Private methods
• Private DOM event handlers
• Private custom event handlers
• Public member variables (properties)
• Public methods
• Public DOM event handlers
• Public custom event handlers

/////////////////////////////////////////////////////////////////////////////
//
// $REGION$
//
/////////////////////////////////////////////////////////////////////////////

Inline Comments

• Mark any known issue or feature request with a TODO comment. (z)
• Mark any code or markup segment that must be finished before release with a FIXME comment. (z)
• File issue tickets for significant TODOs, and cross reference the inline comment. (z)
• Do not use version designations, since Yazaar does not issue versioned releases (only distributions). (z)

Coding Tools

• Validate submissions and revisions with JavaScript Lint or equivalent. (c)
• Do not use HTML Tidy to format test pages, since it upsets the script formatting. (z)
• Do validate all test pages with HTML Tidy or the FireFox HTML validator plugin before committing. (z)

Commit style

All Subversion commits must reference an issue ticket. (So open the ticket first!). (z)

Subversion commit messages are posted to the development group mailing list, for both the code and the wiki. Verbose logs are recommended so as to encourage other developers to peer-review code and documentation. (z)

Notes from Zakas presentation

• http://yuiblog.com/blog/2007/05/25/video-zakas/

• Globals are evil, create namespace objects.

• Indent code (four space increments)
• Comment your code
• Each method
• Large sections of code
• Complex algorithms
• Hacks

• Variable names should be nouns
• Function names should be verbs
• Avoid useless names like foo and bar
• Indicate variable type using Hungarian notation

• Layer code into JavaScript (behavior), CSS (presentation), and HTML (structure) and avoid mixing layers.
• Separate CSS and JavaScript

• Event handlers should handle events, not business logic.
• Encapsulate business logic in separate methods that can called without the event

• Don't modify objects that you don't own

• Validate essential input
• Avoid null comparisons
• instanceof
• typeof

• Throw your own errors

• Use Constants
• Repeated unique values
• UI strings
• URLS
• Any value that might change

• One object or object definition per file
• Rely on build step to combine and minimize files