Blame - javascriptguide.xml - platform/external/google-styleguide

blob: aba5a1eb2c141cd643b50378bcd816e99904f66a [file] [log] [blame]

robbyw@google.com	bb32401	2010-07-12 22:02:20 +0000	[diff] [blame]	1	<?xml version = '1.0'?>
				2	<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
				3	<GUIDE title="Google JavaScript Style Guide">
				4	<p class="revision">
Dan Beam	159b4c8	2016-12-21 16:47:24 -0800	[diff] [blame]	5	Please note: there's a newer version of this guide that includes
				6	ECMAScript 6th Edition features. It lives <a href="jsguide.html">here</a>.
				7	You should probably be using that for new code.
				8
				9	Revision 2.93
robbyw@google.com	bb32401	2010-07-12 22:02:20 +0000	[diff] [blame]	10	</p>
Dan Beam	159b4c8	2016-12-21 16:47:24 -0800	[diff] [blame]	11
				12	<address>
				13	Aaron Whyte<br/>
				14	Bob Jervis<br/>
				15	Dan Pupius<br/>
				16	Erik Arvidsson<br/>
				17	Fritz Schneider<br/>
				18	Robby Walker<br/>
				19	</address>
				20	<OVERVIEW>
				21	<CATEGORY title="Important Note">
				22	<STYLEPOINT title="Displaying Hidden Details in this Guide">
				23	<SUMMARY>
				24	This style guide contains many details that are initially
				25	hidden from view. They are marked by the triangle icon, which you
				26	see here on your left. Click it now.
				27	You should see "Hooray" appear below.
				28	</SUMMARY>
				29	<BODY>
				30	<p>
				31	Hooray! Now you know you can expand points to get more
				32	details. Alternatively, there's a "toggle all" at the
				33	top of this document.
				34	</p>
				35	</BODY>
				36	</STYLEPOINT>
				37	</CATEGORY>
				38	<CATEGORY title="Background">
				39	<p>
				40	JavaScript is the main client-side scripting language used
				41
				42	by many of Google's open-source
				43	projects.
				44	This style guide is a list of <em>do</em>s and <em>don't</em>s for
				45	JavaScript programs.
				46	</p>
				47
				48
				49
				50
				51
				52	</CATEGORY>
				53	</OVERVIEW>
				54	<CATEGORY title="JavaScript Language Rules">
				55
				56
				57
				58
				59	<STYLEPOINT title="var">
				60	<SUMMARY>
				61	Declarations with <code>var</code>: Always
				62	</SUMMARY>
				63	<BODY>
				64	<DECISION>
				65	When you fail to specify <code>var</code>,
				66	the variable gets placed in the global context, potentially clobbering
				67	existing values. Also, if there's no declaration, it's hard to tell in
				68	what scope a variable lives (e.g., it could be in the Document or
				69	Window just as easily as in the local scope). So always declare with
				70	<code>var</code>.
				71	</DECISION>
				72	</BODY>
				73	</STYLEPOINT>
				74
				75	<STYLEPOINT title="Constants">
				76	<SUMMARY>
				77	<ul>
				78	<li>Use <code>NAMES_LIKE_THIS</code> for constant <em>values</em>.</li>
				79	<li>Use <code>@const</code> to indicate a constant (non-overwritable)
				80	<em>pointer</em> (a variable or property).</li>
				81	<li>Never use the
				82	<a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const">
				83	<code>const</code> keyword</a>
				84	as it's not supported in Internet Explorer.</li>
				85	</ul>
				86	</SUMMARY>
				87	<BODY>
				88	<DECISION>
				89	<SUBSECTION title="Constant values">
				90
				91	<p>If a value is intended to be <em>constant</em>
				92	and <em>immutable</em>, it should be given a name
				93	in <code>CONSTANT_VALUE_CASE</code>.
				94	<code>ALL_CAPS</code> additionally implies <code>@const</code>
				95	(that the value is not overwritable).
				96	</p>
				97
				98	<p>Primitive types (<code>number</code>, <code>string</code>,
				99	<code>boolean</code>) are constant values.</p>
				100
				101	<p><code>Objects</code>'
				102	immutability is more subjective — objects should be
				103	considered immutable only if they do not demonstrate observable
				104	state change. This is not enforced by the compiler.</p>
				105
				106
				107	</SUBSECTION>
				108
				109	<SUBSECTION title="Constant pointers (variables and properties)">
				110	<p>The <code>@const</code> annotation on a variable or property
				111	implies that it is not overwritable. This is enforced by the
				112	compiler at build time. This behavior is consistent with the
				113	<a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const">
				114	<code>const</code> keyword</a> (which we do not use due to the
				115	lack of support in Internet Explorer).</p>
				116
				117	<p>A <code>@const</code> annotation on a method additionally
				118	implies that the method cannot not be overridden in subclasses.
				119	</p>
				120
				121	<p>A <code>@const</code> annotation on a constructor implies the
				122	class cannot be subclassed (akin to <code>final</code> in Java).
				123	</p>
				124
				125	</SUBSECTION>
				126
				127	<SUBSECTION title="Examples">
				128
				129	<p>Note that <code>@const</code> does not necessarily imply
				130	<code>CONSTANT_VALUES_CASE</code>.
				131
				132	However, <code>CONSTANT_VALUES_CASE</code>
				133	<em>does</em> imply <code>@const</code>.
				134	</p>
				135
				136	<CODE_SNIPPET>
				137	/**
				138	* Request timeout in milliseconds.
				139	* @type {number}
				140	*/
				141	goog.example.TIMEOUT_IN_MILLISECONDS = 60;
				142	</CODE_SNIPPET>
				143
				144	<p>The number of seconds in a minute never changes. It is a
				145	constant value. <code>ALL_CAPS</code>
				146	also implies <code>@const</code>, so the constant cannot be
				147	overwritten.
				148	</p>
				149
				150	<p>The open source compiler will allow the symbol to be
				151	overwritten because the constant is
				152	<em>not</em> marked as <code>@const</code>.</p>
				153
				154	<CODE_SNIPPET>
				155	/**
				156	* Map of URL to response string.
				157	* @const
				158	*/
				159	MyClass.fetchedUrlCache_ = new goog.structs.Map();
				160	</CODE_SNIPPET>
				161
				162	<CODE_SNIPPET>
				163	/**
				164	* Class that cannot be subclassed.
				165	* @const
				166	* @constructor
				167	*/
				168	sloth.MyFinalClass = function() {};
				169	</CODE_SNIPPET>
				170
				171	<p>In this case, the pointer can never be overwritten, but
				172	value is highly mutable and <b>not</b> constant (and thus in
				173	<code>camelCase</code>, not <code>ALL_CAPS</code>).</p>
				174	</SUBSECTION>
				175
				176	</DECISION>
				177	</BODY>
				178	</STYLEPOINT>
				179
				180	<STYLEPOINT title="Semicolons">
				181	<SUMMARY>
				182	Always use semicolons.
				183	</SUMMARY>
				184	<BODY>
				185	<p>Relying on implicit insertion can cause subtle, hard to debug
				186	problems. Don't do it. You're better than that.</p>
				187	<p>There are a couple places where missing semicolons are particularly
				188	dangerous:</p>
				189	<BAD_CODE_SNIPPET>
				190	// 1.
				191	MyClass.prototype.myMethod = function() {
				192	return 42;
				193	} // No semicolon here.
				194
				195	(function() {
				196	// Some initialization code wrapped in a function to create a scope for locals.
				197	})();
				198
				199
				200	var x = {
				201	'i': 1,
				202	'j': 2
				203	} // No semicolon here.
				204
				205	// 2. Trying to do one thing on Internet Explorer and another on Firefox.
				206	// I know you'd never write code like this, but throw me a bone.
				207	[ffVersion, ieVersion][isIE]();
				208
				209
				210	var THINGS_TO_EAT = [apples, oysters, sprayOnCheese] // No semicolon here.
				211
				212	// 3. conditional execution a la bash
				213	-1 == resultOfOperation() \|\| die();
				214	</BAD_CODE_SNIPPET>
				215	<SUBSECTION title="So what happens?">
				216	<ol>
				217	<li>JavaScript error - first the function returning 42 is called
				218	with the second function as a parameter, then the number 42 is
				219	"called" resulting in an error.</li>
				220	<li>You will most likely get a 'no such property in undefined'
				221	error at runtime as it tries to call
				222	<code>x[ffVersion, ieVersion][isIE]()</code>.</li>
				223	<li><code>die</code> is always called since the array minus 1 is
				224	<code>NaN</code> which is never equal to anything (not even if
				225	<code>resultOfOperation()</code> returns <code>NaN</code>) and
				226	<code>THINGS_TO_EAT</code> gets assigned the result of
				227	<code>die()</code>.</li>
				228	</ol>
				229	</SUBSECTION>
				230	<SUBSECTION title="Why?">
				231	<p>JavaScript requires statements to end with a semicolon, except when
				232	it thinks it can safely infer their existence. In each of these
				233	examples, a function declaration or object or array literal is used
				234	inside a statement. The closing brackets are not enough to signal
				235	the end of the statement. Javascript never ends a statement if the
				236	next token is an infix or bracket operator.</p>
				237	<p>This has really surprised people, so make sure your assignments end
				238	with semicolons.</p>
				239	</SUBSECTION>
				240	<SUBSECTION title="Clarification: Semicolons and functions">
				241	<p>Semicolons should be included at the end of function expressions,
				242	but not at the end of function declarations. The distinction is
				243	best illustrated with an example:</p>
				244	<CODE_SNIPPET>
				245	var foo = function() {
				246	return true;
				247	}; // semicolon here.
				248
				249	function foo() {
				250	return true;
				251	} // no semicolon here.
				252	</CODE_SNIPPET>
				253	</SUBSECTION>
				254	</BODY>
				255	</STYLEPOINT>
				256
				257	<STYLEPOINT title="Nested functions">
				258	<SUMMARY>Yes</SUMMARY>
				259	<BODY>
				260	<p>Nested functions can be very useful, for example in the creation of
				261	continuations and for the task of hiding helper functions. Feel free
				262	to use them.</p>
				263	</BODY>
				264	</STYLEPOINT>
				265
				266	<STYLEPOINT title="Function Declarations Within Blocks">
				267	<SUMMARY>No</SUMMARY>
				268	<BODY>
				269	<p>Do not do this:</p>
				270	<BAD_CODE_SNIPPET>
				271	if (x) {
				272	function foo() {}
				273	}
				274	</BAD_CODE_SNIPPET>
				275
				276	<p>While most script engines support Function Declarations within blocks
				277	it is not part of ECMAScript (see
				278	<a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>,
				279	clause 13 and 14). Worse implementations are inconsistent with each
				280	other and with future EcmaScript proposals. ECMAScript only allows for
				281	Function Declarations in the root statement list of a script or
				282	function. Instead use a variable initialized with a Function
				283	Expression to define a function within a block:</p>
				284	<CODE_SNIPPET>
				285	if (x) {
				286	var foo = function() {};
				287	}
				288	</CODE_SNIPPET>
				289	</BODY>
				290	</STYLEPOINT>
				291
				292	<STYLEPOINT title="Exceptions">
				293	<SUMMARY>Yes</SUMMARY>
				294	<BODY>
				295	<p>You basically can't avoid exceptions if you're doing something
				296	non-trivial (using an application development framework, etc.).
				297	Go for it.</p>
				298	</BODY>
				299	</STYLEPOINT>
				300
				301	<STYLEPOINT title="Custom exceptions">
				302	<SUMMARY>Yes</SUMMARY>
				303	<BODY>
				304	<p>Without custom exceptions, returning error information from a
				305	function that also returns a value can be tricky, not to mention
				306	inelegant. Bad solutions include passing in a reference type to hold
				307	error information or always returning Objects with a potential
				308	error member. These basically amount to a primitive exception
				309	handling hack. Feel free to use custom exceptions when
				310	appropriate.</p>
				311	</BODY>
				312	</STYLEPOINT>
				313
				314	<STYLEPOINT title="Standards features">
				315	<SUMMARY>Always preferred over non-standards features</SUMMARY>
				316	<BODY>
				317	<p>For maximum portability and compatibility, always prefer standards
				318	features over non-standards features (e.g.,
				319	<code>string.charAt(3)</code> over <code>string[3]</code> and element
				320	access with DOM functions instead of using an application-specific
				321	shorthand).</p>
				322	</BODY>
				323	</STYLEPOINT>
				324
				325	<STYLEPOINT title="Wrapper objects for primitive types">
				326	<SUMMARY>No</SUMMARY>
				327	<BODY>
				328	<p>There's no reason to use wrapper objects for primitive types, plus
				329	they're dangerous:</p>
				330	<BAD_CODE_SNIPPET>
				331	var x = new Boolean(false);
				332	if (x) {
				333	alert('hi'); // Shows 'hi'.
				334	}
				335	</BAD_CODE_SNIPPET>
				336	<p>Don't do it!</p>
				337	<p>However type casting is fine.</p>
				338	<CODE_SNIPPET>
				339	var x = Boolean(0);
				340	if (x) {
				341	alert('hi'); // This will never be alerted.
				342	}
				343	typeof Boolean(0) == 'boolean';
				344	typeof new Boolean(0) == 'object';
				345	</CODE_SNIPPET>
				346	<p>This is very useful for casting things to
				347	<code>number</code>, <code>string</code> and <code>boolean</code>.</p>
				348	</BODY>
				349	</STYLEPOINT>
				350
				351	<STYLEPOINT title="Multi-level prototype hierarchies">
				352	<SUMMARY>Not preferred</SUMMARY>
				353	<BODY>
				354	<p>Multi-level prototype hierarchies are how JavaScript implements
				355	inheritance. You have a multi-level hierarchy if you have a
				356	user-defined class D with another user-defined class B as its
				357	prototype. These hierarchies are much harder to get right than they
				358	first appear! </p>
				359
				360	<p>For that reason, it is best to use <code>goog.inherits()</code> from
				361	<a href="https://code.google.com/closure/library/">
				362	the Closure Library
				363	</a>
				364	or a similar library function.
				365	</p>
				366	<CODE_SNIPPET>
				367	function D() {
				368	goog.base(this)
				369	}
				370	goog.inherits(D, B);
				371
				372	D.prototype.method = function() {
				373	...
				374	};
				375	</CODE_SNIPPET>
				376	</BODY>
				377	</STYLEPOINT>
				378
				379	<STYLEPOINT title="Method and property definitions">
				380	<SUMMARY><code>/** @constructor */
				381	function SomeConstructor() {
				382	this.someProperty = 1;
				383	}
				384	Foo.prototype.someMethod = function() { ... };</code></SUMMARY>
				385	<BODY>
				386	<p>While there are several ways to attach methods and properties to an
				387	object created via "new", the preferred style for methods
				388	is:</p>
				389	<CODE_SNIPPET>
				390	Foo.prototype.bar = function() {
				391	/* ... */
				392	};
				393	</CODE_SNIPPET>
				394	<p>The preferred style for other properties is to initialize the field
				395	in the constructor:</p>
				396	<CODE_SNIPPET>
				397	/** @constructor */
				398	function Foo() {
				399	this.bar = value;
				400	}
				401	</CODE_SNIPPET>
				402	<SUBSECTION title="Why?">
				403	<p>Current JavaScript engines optimize based on the "shape"
				404	of an object, <a href="https://developers.google.com/v8/design#prop_access">
				405	adding a property to an object (including overriding
				406	a value set on the prototype) changes the shape and can degrade
				407	performance.</a></p>
				408	</SUBSECTION>
				409	</BODY>
				410	</STYLEPOINT>
				411
				412	<STYLEPOINT title="delete">
				413	<SUMMARY>Prefer <code>this.foo = null</code>.</SUMMARY>
				414	<BODY>
				415	<CODE_SNIPPET>
				416	Foo.prototype.dispose = function() {
				417	this.property_ = null;
				418	};
				419	</CODE_SNIPPET>
				420	<p>Instead of:</p>
				421	<BAD_CODE_SNIPPET>
				422	Foo.prototype.dispose = function() {
				423	delete this.property_;
				424	};
				425	</BAD_CODE_SNIPPET>
				426	<p>In modern JavaScript engines, changing the number of properties on an
				427	object is much slower than reassigning the values. The delete keyword
				428	should be avoided except when it is necessary to remove a property
				429	from an object's iterated list of keys, or to change the result of
				430	<code>if (key in obj)</code>.</p>
				431	</BODY>
				432	</STYLEPOINT>
				433
				434	<STYLEPOINT title="Closures">
				435	<SUMMARY>Yes, but be careful.</SUMMARY>
				436	<BODY>
				437	<p>The ability to create closures is perhaps the most useful and often
				438	overlooked feature of JS. Here is
				439	<a href="http://jibbering.com/faq/faq_notes/closures.html">
				440	a good description of how closures work</a>.</p>
				441	<p>One thing to keep in mind, however, is that a closure keeps a pointer
				442	to its enclosing scope. As a result, attaching a closure to a DOM
				443	element can create a circular reference and thus, a memory leak. For
				444	example, in the following code:</p>
				445	<BAD_CODE_SNIPPET>
				446	function foo(element, a, b) {
				447	element.onclick = function() { /* uses a and b */ };
				448	}
				449	</BAD_CODE_SNIPPET>
				450	<p>the function closure keeps a reference to <code>element</code>,
				451	<code>a</code>, and <code>b</code> even if it never uses
				452	<code>element</code>. Since <code>element</code> also keeps a
				453	reference to the closure, we have a cycle that won't be cleaned up by
				454	garbage collection. In these situations, the code can be structured
				455	as follows:</p>
				456	<CODE_SNIPPET>
				457	function foo(element, a, b) {
				458	element.onclick = bar(a, b);
				459	}
				460
				461	function bar(a, b) {
				462	return function() { /* uses a and b */ };
				463	}
				464	</CODE_SNIPPET>
				465	</BODY>
				466	</STYLEPOINT>
				467
				468	<STYLEPOINT title="eval()">
				469	<SUMMARY>
				470	Only for code loaders and REPL (Read–eval–print loop)
				471	</SUMMARY>
				472	<BODY>
				473	<p><code>eval()</code> makes for confusing semantics and is dangerous
				474	to use if the string being <code>eval()</code>'d contains user input.
				475	There's usually a better, clearer, and safer way to write your code,
				476	so its use is generally not permitted.</p>
				477
				478	<p>For RPC you can always use JSON and read the result using
				479	<code>JSON.parse()</code> instead of <code>eval()</code>.</p>
				480
				481	<p>Let's assume we have a server that returns something like this:</p>
				482
				483	<CODE_SNIPPET>
				484	{
				485	"name": "Alice",
				486	"id": 31502,
				487	"email": "looking_glass@example.com"
				488	}
				489	</CODE_SNIPPET>
				490
				491	<BAD_CODE_SNIPPET>
				492	var userInfo = eval(feed);
				493	var email = userInfo['email'];
				494	</BAD_CODE_SNIPPET>
				495
				496	<p>If the feed was modified to include malicious JavaScript code, then
				497	if we use <code>eval</code> then that code will be executed.</p>
				498
				499	<CODE_SNIPPET>
				500	var userInfo = JSON.parse(feed);
				501	var email = userInfo['email'];
				502	</CODE_SNIPPET>
				503
				504	<p>With <code>JSON.parse</code>, invalid JSON (including all executable
				505	JavaScript) will cause an exception to be thrown.</p>
				506
				507	</BODY>
				508	</STYLEPOINT>
				509
				510	<STYLEPOINT title="with() {}">
				511	<SUMMARY>No</SUMMARY>
				512	<BODY>
				513	<p>Using <code>with</code> clouds the semantics of your program.
				514	Because the object of the <code>with</code> can have properties that
				515	collide with local variables, it can drastically change the meaning
				516	of your program. For example, what does this do?</p>
				517	<BAD_CODE_SNIPPET>
				518	with (foo) {
				519	var x = 3;
				520	return x;
				521	}
				522	</BAD_CODE_SNIPPET>
				523	<p>Answer: anything. The local variable <code>x</code> could be
				524	clobbered by a property of <code>foo</code> and perhaps it even has
				525	a setter, in which case assigning <code>3</code> could cause lots of
				526	other code to execute. Don't use <code>with</code>.</p>
				527	</BODY>
				528	</STYLEPOINT>
				529
				530	<STYLEPOINT title="this">
				531	<SUMMARY>
				532	Only in object constructors, methods, and in setting up closures
				533	</SUMMARY>
				534	<BODY>
				535	<p>The semantics of <code>this</code> can be tricky. At times it refers
				536	to the global object (in most places), the scope of the caller (in
				537	<code>eval</code>), a node in the DOM tree (when attached using an
				538	event handler HTML attribute), a newly created object (in a
				539	constructor), or some other object (if function was
				540	<code>call()</code>ed or <code>apply()</code>ed).</p>
				541	<p>Because this is so easy to get wrong, limit its use to those places
				542	where it is required:</p>
				543	<ul>
				544	<li>in constructors</li>
				545	<li>in methods of objects (including in the creation of closures)</li>
				546	</ul>
				547	</BODY>
				548	</STYLEPOINT>
				549
				550	<STYLEPOINT title="for-in loop">
				551	<SUMMARY>
				552	Only for iterating over keys in an object/map/hash
				553	</SUMMARY>
				554	<BODY>
				555	<p><code>for-in</code> loops are often incorrectly used to loop over
				556	the elements in an <code>Array</code>. This is however very error
				557	prone because it does not loop from <code>0</code> to
				558	<code>length - 1</code> but over all the present keys in the object
				559	and its prototype chain. Here are a few cases where it fails:</p>
				560	<BAD_CODE_SNIPPET>
				561	function printArray(arr) {
				562	for (var key in arr) {
				563	print(arr[key]);
				564	}
				565	}
				566
				567	printArray([0,1,2,3]); // This works.
				568
				569	var a = new Array(10);
				570	printArray(a); // This is wrong.
				571
				572	a = document.getElementsByTagName('*');
				573	printArray(a); // This is wrong.
				574
				575	a = [0,1,2,3];
				576	a.buhu = 'wine';
				577	printArray(a); // This is wrong again.
				578
				579	a = new Array;
				580	a[3] = 3;
				581	printArray(a); // This is wrong again.
				582	</BAD_CODE_SNIPPET>
				583	<p>Always use normal for loops when using arrays.</p>
				584	<CODE_SNIPPET>
				585	function printArray(arr) {
				586	var l = arr.length;
				587	for (var i = 0; i < l; i++) {
				588	print(arr[i]);
				589	}
				590	}
				591	</CODE_SNIPPET>
				592	</BODY>
				593	</STYLEPOINT>
				594
				595	<STYLEPOINT title="Associative Arrays">
				596	<SUMMARY>
				597	Never use <code>Array</code> as a map/hash/associative array
				598	</SUMMARY>
				599	<BODY>
				600	<p>Associative <code>Array</code>s are not allowed... or more precisely
				601	you are not allowed to use non number indexes for arrays. If you need
				602	a map/hash use <code>Object</code> instead of <code>Array</code> in
				603	these cases because the features that you want are actually features
				604	of <code>Object</code> and not of <code>Array</code>.
				605	<code>Array</code> just happens to extend <code>Object</code> (like
				606	any other object in JS and therefore you might as well have used
				607	<code>Date</code>, <code>RegExp</code> or <code>String</code>).</p>
				608	</BODY>
				609	</STYLEPOINT>
				610
				611	<STYLEPOINT title="Multiline string literals">
				612	<SUMMARY>No</SUMMARY>
				613	<BODY>
				614	<p>Do not do this:</p>
				615	<BAD_CODE_SNIPPET>
				616	var myString = 'A rather long string of English text, an error message \
				617	actually that just keeps going and going -- an error \
				618	message to make the Energizer bunny blush (right through \
				619	those Schwarzenegger shades)! Where was I? Oh yes, \
				620	you\'ve got an error and all the extraneous whitespace is \
				621	just gravy. Have a nice day.';
				622	</BAD_CODE_SNIPPET>
				623	<p>The whitespace at the beginning of each line can't be safely stripped
				624	at compile time; whitespace after the slash will result in tricky
				625	errors. </p>
				626	<p>Use string concatenation instead:</p>
				627	<CODE_SNIPPET>
				628	var myString = 'A rather long string of English text, an error message ' +
				629	'actually that just keeps going and going -- an error ' +
				630	'message to make the Energizer bunny blush (right through ' +
				631	'those Schwarzenegger shades)! Where was I? Oh yes, ' +
				632	'you\'ve got an error and all the extraneous whitespace is ' +
				633	'just gravy. Have a nice day.';
				634	</CODE_SNIPPET>
				635	</BODY>
				636	</STYLEPOINT>
				637
				638	<STYLEPOINT title="Array and Object literals">
				639	<SUMMARY>Yes</SUMMARY>
				640	<BODY>
				641	<p>Use <code>Array</code> and <code>Object</code> literals instead of
				642	<code>Array</code> and <code>Object</code> constructors.</p>
				643	<p>Array constructors are error-prone due to their arguments.</p>
				644	<BAD_CODE_SNIPPET>
				645	// Length is 3.
				646	var a1 = new Array(x1, x2, x3);
				647
				648	// Length is 2.
				649	var a2 = new Array(x1, x2);
				650
				651	// If x1 is a number and it is a natural number the length will be x1.
				652	// If x1 is a number but not a natural number this will throw an exception.
				653	// Otherwise the array will have one element with x1 as its value.
				654	var a3 = new Array(x1);
				655
				656	// Length is 0.
				657	var a4 = new Array();
				658	</BAD_CODE_SNIPPET>
				659	<p>Because of this, if someone changes the code to pass 1 argument
				660	instead of 2 arguments, the array might not have the expected
				661	length.</p>
				662	<p>To avoid these kinds of weird cases, always use the more readable
				663	array literal.</p>
				664	<CODE_SNIPPET>
				665	var a = [x1, x2, x3];
				666	var a2 = [x1, x2];
				667	var a3 = [x1];
				668	var a4 = [];
				669	</CODE_SNIPPET>
				670	<p>Object constructors don't have the same problems, but for readability
				671	and consistency object literals should be used.</p>
				672	<BAD_CODE_SNIPPET>
				673	var o = new Object();
				674
				675	var o2 = new Object();
				676	o2.a = 0;
				677	o2.b = 1;
				678	o2.c = 2;
				679	o2['strange key'] = 3;
				680	</BAD_CODE_SNIPPET>
				681	<p>Should be written as:</p>
				682	<CODE_SNIPPET>
				683	var o = {};
				684
				685	var o2 = {
				686	a: 0,
				687	b: 1,
				688	c: 2,
				689	'strange key': 3
				690	};
				691	</CODE_SNIPPET>
				692	</BODY>
				693	</STYLEPOINT>
				694
				695	<STYLEPOINT title="Modifying prototypes of builtin objects">
				696	<SUMMARY>No</SUMMARY>
				697	<BODY>
				698	<p>Modifying builtins like <code>Object.prototype</code> and
				699	<code>Array.prototype</code> are strictly forbidden. Modifying other
				700	builtins like <code>Function.prototype</code> is less dangerous but
				701	still leads to hard to debug issues in production and should be
				702	avoided.</p>
				703	</BODY>
				704	</STYLEPOINT>
				705
				706	<STYLEPOINT title="Internet Explorer's Conditional Comments">
				707	<SUMMARY>No</SUMMARY>
				708	<BODY>
				709	<p>Don't do this:</p>
				710	<BAD_CODE_SNIPPET>
				711	var f = function () {
				712	/@cc_on if (@_jscript) { return 2 @/ 3; /@ } @*/
				713	};
				714	</BAD_CODE_SNIPPET>
				715	<p>Conditional Comments hinder automated tools as they can vary the
				716	JavaScript syntax tree at runtime.</p>
				717	</BODY>
				718	</STYLEPOINT>
				719	</CATEGORY>
				720
				721	<CATEGORY title="JavaScript Style Rules">
				722	<STYLEPOINT title="Naming">
				723	<SUMMARY>
				724	<p>In general, use
				725	<code>functionNamesLikeThis</code>,
				726	<code>variableNamesLikeThis</code>,
				727	<code>ClassNamesLikeThis</code>,
				728	<code>EnumNamesLikeThis</code>,
				729	<code>methodNamesLikeThis</code>,
				730	<code>CONSTANT_VALUES_LIKE_THIS</code>,
				731	<code>foo.namespaceNamesLikeThis.bar</code>, and
				732	<code>filenameslikethis.js</code>.
				733	</p>
				734	</SUMMARY>
				735	<BODY>
				736	<SUBSECTION title="Properties and methods">
				737	<ul>
				738	<li><em>Private</em> properties and methods should be named with a
				739	trailing underscore.
				740	</li>
				741	<li><em>Protected</em> properties and methods should be
				742	named without a trailing underscore (like public ones).</li>
				743	</ul>
				744	<p>For more information on <em>private</em> and <em>protected</em>,
				745	read the section on
				746	<a href="#Visibility__private_and_protected_fields_">
				747	visibility</a>.
				748	</p>
				749
				750
				751
				752
				753	</SUBSECTION>
				754
				755	<SUBSECTION title="Method and function parameter">
				756	<p>Optional function arguments start with <code>opt_</code>.</p>
				757	<p>Functions that take a variable number of arguments should have the
				758	last argument named <code>var_args</code>. You may not refer to
				759	<code>var_args</code> in the code; use the <code>arguments</code>
				760	array.</p>
				761	<p>Optional and variable arguments can also be specified in
				762	<code>@param</code> annotations. Although either convention is
				763	acceptable to the compiler, using both together is preferred.</p>
				764
				765	</SUBSECTION>
				766
				767	<SUBSECTION title="Getters and Setters">
				768	<p>EcmaScript 5 getters and setters for properties are discouraged.
				769	However, if they are used, then getters must not change observable
				770	state.</p>
				771	<BAD_CODE_SNIPPET>
				772	/**
				773	* WRONG -- Do NOT do this.
				774	*/
				775	var foo = { get next() { return this.nextId++; } };
				776	</BAD_CODE_SNIPPET>
				777	</SUBSECTION>
				778
				779	<SUBSECTION title="Accessor functions">
				780	<p>Getters and setters methods for properties are not required.
				781	However, if they are used, then getters must be named
				782	<code>getFoo()</code> and setters must be named
				783	<code>setFoo(value)</code>. (For boolean getters,
				784	<code>isFoo()</code> is also acceptable, and often sounds more
				785	natural.)</p>
				786	</SUBSECTION>
				787
				788	<SUBSECTION title="Namespaces">
				789	<p>JavaScript has no inherent packaging or namespacing support.</p>
				790	<p>Global name conflicts are difficult to debug, and can cause
				791	intractable problems when two projects try to integrate. In order
				792	to make it possible to share common JavaScript code, we've adopted
				793	conventions to prevent collisions. </p>
				794	<SUBSUBSECTION title="Use namespaces for global code">
				795	<p><em>ALWAYS</em> prefix identifiers in the global scope with a
				796	unique pseudo namespace related to the project or library. If you
				797	are working on "Project Sloth", a reasonable pseudo namespace
				798	would be <code>sloth.*</code>.</p>
				799	<CODE_SNIPPET>
				800	var sloth = {};
				801
				802	sloth.sleep = function() {
				803	...
				804	};
				805	</CODE_SNIPPET>
				806
				807
				808	<p>Many JavaScript libraries, including
				809	<a href="https://code.google.com/closure/library/">
				810	the Closure Library
				811	</a>
				812	and
				813	<a href="http://www.dojotoolkit.org/">
				814	Dojo toolkit
				815	</a>
				816	give you high-level functions for declaring your namespaces.
				817	Be consistent about how you declare your namespaces.</p>
				818	<CODE_SNIPPET>
				819	goog.provide('sloth');
				820
				821	sloth.sleep = function() {
				822	...
				823	};
				824	</CODE_SNIPPET>
				825	</SUBSUBSECTION>
				826	<SUBSUBSECTION title="Respect namespace ownership">
				827	<p>When choosing a child-namespace, make sure that the owners of the
				828	parent namespace know what you are doing. If you start a project
				829	that creates hats for sloths, make sure that the Sloth team knows
				830	that you're using <code>sloth.hats</code>.</p>
				831
				832	</SUBSUBSECTION>
				833	<SUBSUBSECTION title="Use different namespaces for external code and internal code">
				834	<p>"External code" is code that comes from outside your codebase,
				835	and is compiled independently. Internal and external names should
				836	be kept strictly separate. If you're using an external library
				837	that makes things available in <code>foo.hats.*</code>, your
				838	internal code should not define all its symbols in
				839	<code>foo.hats.*</code>, because it will break if the other
				840	team defines new symbols.</p>
				841	<BAD_CODE_SNIPPET>
				842	foo.require('foo.hats');
				843
				844	/**
				845	* WRONG -- Do NOT do this.
				846	* @constructor
				847	* @extends {foo.hats.RoundHat}
				848	*/
				849	foo.hats.BowlerHat = function() {
				850	};
				851	</BAD_CODE_SNIPPET>
				852	<p>If you need to define new APIs on an external namespace, then you
				853	should explicitly export the public API functions, and only those
				854	functions. Your internal code should call the internal APIs by
				855	their internal names, for consistency and so that the compiler
				856	can optimize them better.</p>
				857	<CODE_SNIPPET>
				858	foo.provide('googleyhats.BowlerHat');
				859
				860	foo.require('foo.hats');
				861
				862	/**
				863	* @constructor
				864	* @extends {foo.hats.RoundHat}
				865	*/
				866	googleyhats.BowlerHat = function() {
				867	...
				868	};
				869
				870	goog.exportSymbol('foo.hats.BowlerHat', googleyhats.BowlerHat);
				871	</CODE_SNIPPET>
				872
				873
				874	</SUBSUBSECTION>
				875	<SUBSUBSECTION title="Alias long type names to improve readability">
				876	<p>Use local aliases for fully-qualified types if doing so improves
				877	readability. The name of a local alias should match the last part
				878	of the type.</p>
				879	<CODE_SNIPPET>
				880	/**
				881	* @constructor
				882	*/
				883	some.long.namespace.MyClass = function() {
				884	};
				885
				886	/**
				887	* @param {some.long.namespace.MyClass} a
				888	*/
				889	some.long.namespace.MyClass.staticHelper = function(a) {
				890	...
				891	};
				892
				893	myapp.main = function() {
				894	var MyClass = some.long.namespace.MyClass;
				895	var staticHelper = some.long.namespace.MyClass.staticHelper;
				896	staticHelper(new MyClass());
				897	};
				898	</CODE_SNIPPET>
				899	<p>Do not create local aliases of namespaces. Namespaces should only
				900	be aliased using <a href="#goog-scope">goog.scope</a>.</p>
				901	<BAD_CODE_SNIPPET>
				902	myapp.main = function() {
				903	var namespace = some.long.namespace;
				904	namespace.MyClass.staticHelper(new namespace.MyClass());
				905	};
				906	</BAD_CODE_SNIPPET>
				907	<p>Avoid accessing properties of an aliased type, unless it is an
				908	enum.</p>
				909	<CODE_SNIPPET>
				910	/** @enum {string} */
				911	some.long.namespace.Fruit = {
				912	APPLE: 'a',
				913	BANANA: 'b'
				914	};
				915
				916	myapp.main = function() {
				917	var Fruit = some.long.namespace.Fruit;
				918	switch (fruit) {
				919	case Fruit.APPLE:
				920	...
				921	case Fruit.BANANA:
				922	...
				923	}
				924	};
				925	</CODE_SNIPPET>
				926	<BAD_CODE_SNIPPET>
				927	myapp.main = function() {
				928	var MyClass = some.long.namespace.MyClass;
				929	MyClass.staticHelper(null);
				930	};
				931	</BAD_CODE_SNIPPET>
				932	<p>Never create aliases in the global scope. Use them only in
				933	function blocks.</p>
				934	</SUBSUBSECTION>
				935	</SUBSECTION>
				936	<SUBSECTION title="Filenames">
				937	<p>Filenames should be all lowercase in order to avoid confusion on
				938	case-sensitive platforms. Filenames should end in <code>.js</code>,
				939	and should contain no punctuation except for <code>-</code> or
				940	<code>_</code> (prefer <code>-</code> to <code>_</code>).</p>
				941	</SUBSECTION>
				942
				943	</BODY>
				944	</STYLEPOINT>
				945
				946	<STYLEPOINT title="Custom toString() methods">
				947	<SUMMARY>
				948	Must always succeed without side effects.
				949	</SUMMARY>
				950	<BODY>
				951	<p>You can control how your objects string-ify themselves by defining a
				952	custom <code>toString()</code> method. This is fine, but you need
				953	to ensure that your method (1) always succeeds and (2) does not have
				954	side-effects. If your method doesn't meet these criteria, it's very
				955	easy to run into serious problems. For example, if
				956	<code>toString()</code> calls a method that does an
				957	<code>assert</code>, <code>assert</code> might try to output the name
				958	of the object in which it failed, which of course requires calling
				959	<code>toString()</code>.</p>
				960	</BODY>
				961	</STYLEPOINT>
				962
				963	<STYLEPOINT title="Deferred initialization">
				964	<SUMMARY>OK</SUMMARY>
				965	<BODY>
				966	<p>It isn't always possible to initialize variables at the point of
				967	declaration, so deferred initialization is fine.</p>
				968	</BODY>
				969	</STYLEPOINT>
				970
				971	<STYLEPOINT title="Explicit scope">
				972	<SUMMARY>Always</SUMMARY>
				973	<BODY>
				974	<p>Always use explicit scope - doing so increases portability and
				975	clarity. For example, don't rely on <code>window</code> being in the
				976	scope chain. You might want to use your function in another
				977	application for which <code>window</code> is not the content
				978	window.</p>
				979	</BODY>
				980	</STYLEPOINT>
				981
				982	<STYLEPOINT title="Code formatting">
				983	<SUMMARY>Expand for more information.</SUMMARY>
				984	<BODY>
				985	<p>We follow the <a href="cppguide.html#Formatting">C++ formatting
				986	rules</a> in spirit, with the following additional clarifications.</p>
				987	<SUBSECTION title="Curly Braces">
				988	<p>Because of implicit semicolon insertion, always start your curly
				989	braces on the same line as whatever they're opening. For
				990	example:</p>
				991	<CODE_SNIPPET>
				992	if (something) {
				993	// ...
				994	} else {
				995	// ...
				996	}
				997	</CODE_SNIPPET>
				998	</SUBSECTION>
				999	<SUBSECTION title="Array and Object Initializers">
				1000	<p>Single-line array and object initializers are allowed when they
				1001	fit on a line:</p>
				1002	<CODE_SNIPPET>
				1003	var arr = [1, 2, 3]; // No space after [ or before ].
				1004	var obj = {a: 1, b: 2, c: 3}; // No space after { or before }.
				1005	</CODE_SNIPPET>
				1006	<p>Multiline array initializers and object initializers are indented
				1007	2 spaces, with the braces on their own line, just like blocks.</p>
				1008	<CODE_SNIPPET>
				1009	// Object initializer.
				1010	var inset = {
				1011	top: 10,
				1012	right: 20,
				1013	bottom: 15,
				1014	left: 12
				1015	};
				1016
				1017	// Array initializer.
				1018	this.rows_ = [
				1019	'"Slartibartfast" <fjordmaster@magrathea.com>',
				1020	'"Zaphod Beeblebrox" <theprez@universe.gov>',
				1021	'"Ford Prefect" <ford@theguide.com>',
				1022	'"Arthur Dent" <has.no.tea@gmail.com>',
				1023	'"Marvin the Paranoid Android" <marv@googlemail.com>',
				1024	'the.mice@magrathea.com'
				1025	];
				1026
				1027	// Used in a method call.
				1028	goog.dom.createDom(goog.dom.TagName.DIV, {
				1029	id: 'foo',
				1030	className: 'some-css-class',
				1031	style: 'display:none'
				1032	}, 'Hello, world!');
				1033	</CODE_SNIPPET>
				1034	<p>Long identifiers or values present problems for aligned
				1035	initialization lists, so always prefer non-aligned initialization.
				1036	For example:</p>
				1037	<CODE_SNIPPET>
				1038	CORRECT_Object.prototype = {
				1039	a: 0,
				1040	b: 1,
				1041	lengthyName: 2
				1042	};
				1043	</CODE_SNIPPET>
				1044	<p>Not like this:</p>
				1045	<BAD_CODE_SNIPPET>
				1046	WRONG_Object.prototype = {
				1047	a : 0,
				1048	b : 1,
				1049	lengthyName: 2
				1050	};
				1051	</BAD_CODE_SNIPPET>
				1052	</SUBSECTION>
				1053	<SUBSECTION title="Function Arguments">
				1054	<p>When possible, all function arguments should be listed on the same
				1055	line. If doing so would exceed the 80-column limit, the arguments
				1056	must be line-wrapped in a readable way. To save space, you may wrap
				1057	as close to 80 as possible, or put each argument on its own line to
				1058	enhance readability. The indentation may be either four spaces, or
				1059	aligned to the parenthesis. Below are the most common patterns for
				1060	argument wrapping:</p>
				1061	<CODE_SNIPPET>
				1062	// Four-space, wrap at 80. Works with very long function names, survives
				1063	// renaming without reindenting, low on space.
				1064	goog.foo.bar.doThingThatIsVeryDifficultToExplain = function(
				1065	veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
				1066	tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
				1067	// ...
				1068	};
				1069
				1070	// Four-space, one argument per line. Works with long function names,
				1071	// survives renaming, and emphasizes each argument.
				1072	goog.foo.bar.doThingThatIsVeryDifficultToExplain = function(
				1073	veryDescriptiveArgumentNumberOne,
				1074	veryDescriptiveArgumentTwo,
				1075	tableModelEventHandlerProxy,
				1076	artichokeDescriptorAdapterIterator) {
				1077	// ...
				1078	};
				1079
				1080	// Parenthesis-aligned indentation, wrap at 80. Visually groups arguments,
				1081	// low on space.
				1082	function foo(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
				1083	tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
				1084	// ...
				1085	}
				1086
				1087	// Parenthesis-aligned, one argument per line. Emphasizes each
				1088	// individual argument.
				1089	function bar(veryDescriptiveArgumentNumberOne,
				1090	veryDescriptiveArgumentTwo,
				1091	tableModelEventHandlerProxy,
				1092	artichokeDescriptorAdapterIterator) {
				1093	// ...
				1094	}
				1095	</CODE_SNIPPET>
				1096	<p>When the function call is itself indented, you're free to start the
				1097	4-space indent relative to the beginning of the original statement
				1098	or relative to the beginning of the current function call.
				1099	The following are all acceptable indentation styles.</p>
				1100	<CODE_SNIPPET>
				1101	if (veryLongFunctionNameA(
				1102	veryLongArgumentName) \|\|
				1103	veryLongFunctionNameB(
				1104	veryLongArgumentName)) {
				1105	veryLongFunctionNameC(veryLongFunctionNameD(
				1106	veryLongFunctioNameE(
				1107	veryLongFunctionNameF)));
				1108	}
				1109	</CODE_SNIPPET>
				1110	</SUBSECTION>
				1111	<SUBSECTION title="Passing Anonymous Functions">
				1112	<p>When declaring an anonymous function in the list of arguments for
				1113	a function call, the body of the function is indented two spaces
				1114	from the left edge of the statement, or two spaces from the left
				1115	edge of the function keyword. This is to make the body of the
				1116	anonymous function easier to read (i.e. not be all squished up into
				1117	the right half of the screen).</p>
				1118	<CODE_SNIPPET>
				1119	prefix.something.reallyLongFunctionName('whatever', function(a1, a2) {
				1120	if (a1.equals(a2)) {
				1121	someOtherLongFunctionName(a1);
				1122	} else {
				1123	andNowForSomethingCompletelyDifferent(a2.parrot);
				1124	}
				1125	});
				1126
				1127	var names = prefix.something.myExcellentMapFunction(
				1128	verboselyNamedCollectionOfItems,
				1129	function(item) {
				1130	return item.name;
				1131	});
				1132	</CODE_SNIPPET>
				1133	</SUBSECTION>
				1134	<SUBSECTION title="Aliasing with goog.scope">
				1135	<a name="goog-scope"/>
				1136	<p>
				1137	<a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a>
				1138	may be used to shorten references to
				1139	namespaced symbols in programs using
				1140	<a href="https://code.google.com/closure/library/">the Closure
				1141	Library</a>.</p>
				1142	<p>Only one <code>goog.scope</code> invocation may be added per
				1143	file. Always place it in the global scope.</p>
				1144	<p>The opening <code>goog.scope(function() {</code> invocation
				1145	must be preceded by exactly one blank line and follow any
				1146	<code>goog.provide</code> statements, <code>goog.require</code>
				1147	statements, or top-level comments. The invocation must be closed on
				1148	the last line in the file. Append <code>// goog.scope</code> to the
				1149	closing statement of the scope. Separate the comment from the
				1150	semicolon by two spaces.</p>
				1151	<p>Similar to C++ namespaces, do not indent under goog.scope
				1152	declarations. Instead, continue from the 0 column.</p>
				1153	<p>Only alias names that will not be re-assigned to another object
				1154	(e.g., most constructors, enums, and namespaces). Do not do
				1155	this (see below for how to alias a constructor):</p>
				1156
				1157	<BAD_CODE_SNIPPET>
				1158	goog.scope(function() {
				1159	var Button = goog.ui.Button;
				1160
				1161	Button = function() { ... };
				1162	...
				1163	</BAD_CODE_SNIPPET>
				1164
				1165	<p>Names must be the same as the last property of the global that they
				1166	are aliasing.</p>
				1167
				1168	<CODE_SNIPPET>
				1169	goog.provide('my.module.SomeType');
				1170
				1171	goog.require('goog.dom');
				1172	goog.require('goog.ui.Button');
				1173
				1174	goog.scope(function() {
				1175	var Button = goog.ui.Button;
				1176	var dom = goog.dom;
				1177
				1178	// Alias new types <b>after</b> the constructor declaration.
				1179	my.module.SomeType = function() { ... };
				1180	var SomeType = my.module.SomeType;
				1181
				1182	// Declare methods on the prototype as usual:
				1183	SomeType.prototype.findButton = function() {
				1184	// Button as aliased above.
				1185	this.button = new Button(dom.getElement('my-button'));
				1186	};
				1187	...
				1188	}); // goog.scope
				1189	</CODE_SNIPPET>
				1190	</SUBSECTION>
				1191	<SUBSECTION title="Indenting wrapped lines">
				1192	<p>Except for <a href="#Array_and_Object_literals">array literals,
				1193	object literals</a>, and anonymous functions, all wrapped lines
				1194	should be indented either left-aligned to a sibling expression
				1195	above, or four spaces (not two spaces) deeper than a parent
				1196	expression (where "sibling" and "parent" refer to parenthesis
				1197	nesting level).
				1198	</p>
				1199
				1200	<CODE_SNIPPET>
				1201	someWonderfulHtml = '<div class="' + getClassesForWonderfulHtml()'">' +
				1202	getEvenMoreHtml(someReallyInterestingValues, moreValues,
				1203	evenMoreParams, 'a duck', true, 72,
				1204	slightlyMoreMonkeys(0xfff)) +
				1205	'</div>';
				1206
				1207	thisIsAVeryLongVariableName =
				1208	hereIsAnEvenLongerOtherFunctionNameThatWillNotFitOnPrevLine();
				1209
				1210	thisIsAVeryLongVariableName = siblingOne + siblingTwo + siblingThree +
				1211	siblingFour + siblingFive + siblingSix + siblingSeven +
				1212	moreSiblingExpressions + allAtTheSameIndentationLevel;
				1213
				1214	thisIsAVeryLongVariableName = operandOne + operandTwo + operandThree +
				1215	operandFour + operandFive * (
				1216	aNestedChildExpression + shouldBeIndentedMore);
				1217
				1218	someValue = this.foo(
				1219	shortArg,
				1220	'Some really long string arg - this is a pretty common case, actually.',
				1221	shorty2,
				1222	this.bar());
				1223
				1224	if (searchableCollection(allYourStuff).contains(theStuffYouWant) &&
				1225	!ambientNotification.isActive() && (client.isAmbientSupported() \|\|
				1226	client.alwaysTryAmbientAnyways())) {
				1227	ambientNotification.activate();
				1228	}
				1229	</CODE_SNIPPET>
				1230	</SUBSECTION>
				1231	<SUBSECTION title="Blank lines">
				1232	<p>Use newlines to group logically related pieces of code.
				1233	For example:</p>
				1234	<CODE_SNIPPET>
				1235	doSomethingTo(x);
				1236	doSomethingElseTo(x);
				1237	andThen(x);
				1238
				1239	nowDoSomethingWith(y);
				1240
				1241	andNowWith(z);
				1242	</CODE_SNIPPET>
				1243	</SUBSECTION>
				1244	<SUBSECTION title="Binary and Ternary Operators">
				1245	<p>Always put the operator on the preceding line. Otherwise,
				1246	line breaks and indentation follow the same rules as in other
				1247	Google style guides. This operator placement was initially agreed
				1248	upon out of concerns about automatic semicolon insertion. In fact,
				1249	semicolon insertion cannot happen before a binary operator, but new
				1250	code should stick to this style for consistency.</p>
				1251	<CODE_SNIPPET>
				1252	var x = a ? b : c; // All on one line if it will fit.
				1253
				1254	// Indentation +4 is OK.
				1255	var y = a ?
				1256	longButSimpleOperandB : longButSimpleOperandC;
				1257
				1258	// Indenting to the line position of the first operand is also OK.
				1259	var z = a ?
				1260	moreComplicatedB :
				1261	moreComplicatedC;
				1262	</CODE_SNIPPET>
				1263	<p>This includes the dot operator.</p>
				1264	<CODE_SNIPPET>
				1265	var x = foo.bar().
				1266	doSomething().
				1267	doSomethingElse();
				1268	</CODE_SNIPPET>
				1269	</SUBSECTION>
				1270	</BODY>
				1271	</STYLEPOINT>
				1272
				1273	<STYLEPOINT title="Parentheses">
				1274	<SUMMARY>Only where required</SUMMARY>
				1275	<BODY>
				1276	<p>Use sparingly and in general only where required by the syntax
				1277	and semantics.</p>
				1278	<p>Never use parentheses for unary operators such as
				1279	<code>delete</code>, <code>typeof</code> and <code>void</code> or
				1280	after keywords such as <code>return</code>, <code>throw</code> as
				1281	well as others (<code>case</code>, <code>in</code> or
				1282	<code>new</code>).</p>
				1283	</BODY>
				1284	</STYLEPOINT>
				1285
				1286	<STYLEPOINT title="Strings">
				1287	<SUMMARY>Prefer ' over "</SUMMARY>
				1288	<BODY>
				1289	<p>For consistency single-quotes (') are preferred to double-quotes (").
				1290	This is helpful when creating strings that include HTML:</p>
				1291	<CODE_SNIPPET>
				1292	var msg = 'This is <a href="http://foo">some HTML</a>';
				1293	</CODE_SNIPPET>
				1294	</BODY>
				1295	</STYLEPOINT>
				1296
				1297	<STYLEPOINT title="Visibility (private and protected fields)">
				1298	<SUMMARY>Encouraged, use JSDoc annotations <code>@private</code> and
				1299	<code>@protected</code></SUMMARY>
				1300	<BODY>
				1301	<p>We recommend the use of the JSDoc annotations <code>@private</code> and
				1302	<code>@protected</code> to indicate visibility levels for classes,
				1303	functions, and properties.</p>
				1304	<p>The --jscomp_warning=visibility compiler flag turns on compiler
				1305	warnings for visibility violations. See
				1306	<a href="https://code.google.com/p/closure-compiler/wiki/Warnings">
				1307	Closure Compiler
				1308	Warnings</a>.
				1309	</p>
				1310	<p><code>@private</code> global variables and functions are only
				1311	accessible to code in the same file.</p>
				1312	<p>Constructors marked <code>@private</code> may only be instantiated by
				1313	code in the same file and by their static and instance members.
				1314	<code>@private</code> constructors may also be accessed anywhere in the
				1315	same file for their public static properties and by the
				1316	<code>instanceof</code> operator.</p>
				1317	<p>Global variables, functions, and constructors should never be
				1318	annotated <code>@protected</code>.</p>
				1319	<CODE_SNIPPET>
				1320	// File 1.
				1321	// AA_PrivateClass_ and AA_init_ are accessible because they are global
				1322	// and in the same file.
				1323
				1324	/**
				1325	* @private
				1326	* @constructor
				1327	*/
				1328	AA_PrivateClass_ = function() {
				1329	};
				1330
				1331	/** @private */
				1332	function AA_init_() {
				1333	return new AA_PrivateClass_();
				1334	}
				1335
				1336	AA_init_();
				1337	</CODE_SNIPPET>
				1338	<p><code>@private</code> properties are accessible to all code in the
				1339	same file, plus all static methods and instance methods of that class
				1340	that "owns" the property, if the property belongs to a class. They
				1341	cannot be accessed or overridden from a subclass in a different file.</p>
				1342	<p><code>@protected</code> properties are accessible to all code in the
				1343	same file, plus any static methods and instance methods of any subclass
				1344	of a class that "owns" the property.</p>
				1345	<p>Note that these semantics differ from those of C++ and Java, in that
				1346	they grant private and protected access to all code in the same file,
				1347	not just in the same class or class hierarchy. Also, unlike in C++,
				1348	private properties cannot be overridden by a subclass.
				1349	</p>
				1350	<CODE_SNIPPET>
				1351	// File 1.
				1352
				1353	/** @constructor */
				1354	AA_PublicClass = function() {
				1355	/** @private */
				1356	this.privateProp_ = 2;
				1357
				1358	/** @protected */
				1359	this.protectedProp = 4;
				1360	};
				1361
				1362	/** @private */
				1363	AA_PublicClass.staticPrivateProp_ = 1;
				1364
				1365	/** @protected */
				1366	AA_PublicClass.staticProtectedProp = 31;
				1367
				1368	/** @private */
				1369	AA_PublicClass.prototype.privateMethod_ = function() {};
				1370
				1371	/** @protected */
				1372	AA_PublicClass.prototype.protectedMethod = function() {};
				1373
				1374	// File 2.
				1375
				1376	/**
				1377	* @return {number} The number of ducks we've arranged in a row.
				1378	*/
				1379	AA_PublicClass.prototype.method = function() {
				1380	// Legal accesses of these two properties.
				1381	return this.privateProp_ + AA_PublicClass.staticPrivateProp_;
				1382	};
				1383
				1384	// File 3.
				1385
				1386	/**
				1387	* @constructor
				1388	* @extends {AA_PublicClass}
				1389	*/
				1390	AA_SubClass = function() {
				1391	// Legal access of a protected static property.
				1392	AA_PublicClass.staticProtectedProp = this.method();
				1393	};
				1394	goog.inherits(AA_SubClass, AA_PublicClass);
				1395
				1396	/**
				1397	* @return {number} The number of ducks we've arranged in a row.
				1398	*/
				1399	AA_SubClass.prototype.method = function() {
				1400	// Legal access of a protected instance property.
				1401	return this.protectedProp;
				1402	};
				1403	</CODE_SNIPPET>
				1404
				1405	<p>Notice that in JavaScript, there is no distinction between a type
				1406	(like <code>AA_PrivateClass_</code>) and the constructor for that
				1407	type. There is no way to express both that a type is public and its
				1408	constructor is private (because the constructor could easily be aliased
				1409	in a way that would defeat the privacy check).</p>
				1410	</BODY>
				1411	</STYLEPOINT>
				1412
				1413	<STYLEPOINT title="JavaScript Types">
				1414	<SUMMARY>Encouraged and enforced by the compiler.</SUMMARY>
				1415	<BODY>
				1416	<a name="JsTypes"/>
				1417	<p>When documenting a type in JSDoc, be as specific and accurate as
				1418	possible. The types we support are based on the
				1419	<a href="http://wiki.ecmascript.org/doku.php?id=spec:spec">
				1420	EcmaScript 4 spec</a>.</p>
				1421	<SUBSECTION title="The JavaScript Type Language">
				1422	<p>The ES4 proposal contained a language for specifying JavaScript
				1423	types. We use this language in JsDoc to express the types of
				1424	function parameters and return values.</p>
				1425
				1426	<p>As the ES4 proposal has evolved, this language has changed. The
				1427	compiler still supports old syntaxes for types, but those syntaxes
				1428	are deprecated.</p>
				1429
				1430	<p/>
				1431	<table border="1" style="border-collapse:collapse" cellpadding="4">
				1432	<thead>
				1433	<tr>
				1434	<th>Syntax Name</th>
				1435	<th>Syntax</th>
				1436	<th>Description</th>
				1437	<th>Deprecated Syntaxes</th>
				1438	</tr>
				1439	</thead>
				1440	<tbody>
				1441	<tr>
				1442	<td>Primitive Type</td>
				1443	<td>
				1444	There are 5 primitive types in JavaScript:
				1445	<code>{null}</code>,
				1446	<code>{undefined}</code>,
				1447	<code>{boolean}</code>,
				1448	<code>{number}</code>, and
				1449	<code>{string}</code>.
				1450	</td>
				1451	<td>Simply the name of a type.</td>
				1452	<td/>
				1453	</tr>
				1454
				1455	<tr>
				1456	<td>Instance Type</td>
				1457	<td>
				1458	<code>{Object}</code><br/>
				1459	An instance of Object or null.<p/>
				1460	<code>{Function}</code><br/>
				1461	An instance of Function or null.<p/>
				1462	<code>{EventTarget}</code><br/>
				1463	An instance of a constructor that implements the EventTarget
				1464	interface, or null.
				1465	</td>
				1466	<td>An instance of a constructor or interface function.<p/>
				1467
				1468	Constructor functions are functions defined with the
				1469	<code>@constructor</code> JSDoc tag.
				1470	Interface functions are functions defined with the
				1471	<code>@interface</code> JSDoc tag.<p/>
				1472
				1473	By default, instance types will accept null. This is the only
				1474	type syntax that makes the type nullable. Other type syntaxes
				1475	in this table will not accept null.
				1476	</td>
				1477	<td/>
				1478	</tr>
				1479
				1480	<tr>
				1481	<td>Enum Type</td>
				1482	<td>
				1483	<code>{goog.events.EventType}</code><br/>
				1484	One of the properties of the object literal initializer
				1485	of <code>goog.events.EventType</code>.
				1486	</td>
				1487	<td>An enum must be initialized as an object literal, or as
				1488	an alias of another enum, annotated with the <code>@enum</code>
				1489	JSDoc tag. The properties of this literal are the instances
				1490	of the enum. The syntax of the enum is defined
				1491	<a href="#enums">below</a>.<p/>
				1492
				1493	Note that this is one of the few things in our type system
				1494	that were not in the ES4 spec.
				1495	</td>
				1496	<td/>
				1497	</tr>
				1498
				1499	<tr>
				1500	<td>Type Application</td>
				1501	<td>
				1502	<code>{Array.<string>}</code><br/>An array of strings.<p/>
				1503	<code>{Object.<string, number>}</code>
				1504	<br/>An object in which the keys are strings and the values
				1505	are numbers.
				1506	</td>
				1507	<td>Parameterizes a type, by applying a set of type arguments
				1508	to that type. The idea is analogous to generics in Java.
				1509	</td>
				1510	<td/>
				1511	</tr>
				1512
				1513	<tr>
				1514	<td>Type Union</td>
				1515	<td>
				1516	<code>{(number\|boolean)}</code><br/>A number or a boolean.
				1517	</td>
				1518	<td>Indicates that a value might have type A OR type B.<p/>
				1519
				1520	The parentheses may be omitted at the top-level
				1521	expression, but the parentheses should be included in
				1522	sub-expressions to avoid ambiguity.<br/>
				1523	<code>{number\|boolean}</code><br/>
				1524	<code>{function(): (number\|boolean)}</code>
				1525	</td>
				1526	<td>
				1527	<code>{(number,boolean)}</code>,<br/>
				1528	<code>{(number\|\|boolean)}</code>
				1529	</td>
				1530	</tr>
				1531
				1532	<tr>
				1533	<td>Nullable type</td>
				1534	<td>
				1535	<code>{?number}</code><br/> A number or null.
				1536	</td>
				1537	<td>Shorthand for the union of the null type with any
				1538	other type. This is just syntactic sugar.
				1539	</td>
				1540	<td>
				1541	<code>{number?}</code>
				1542	</td>
				1543	</tr>
				1544
				1545	<tr>
				1546	<td>Non-nullable type</td>
				1547	<td>
				1548	<code>{!Object}</code><br/> An Object, but never the
				1549	<code>null</code> value.
				1550	</td>
				1551	<td>Filters null out of nullable types. Most often used
				1552	with instance types, which are nullable by default.
				1553	</td>
				1554	<td>
				1555	<code>{Object!}</code>
				1556	</td>
				1557	</tr>
				1558
				1559	<tr>
				1560	<td>Record Type</td>
				1561	<td>
				1562	<code>{{myNum: number, myObject}}</code>
				1563	<br/>An anonymous type with the given type members.
				1564	</td>
				1565	<td>
				1566	<p>Indicates that the value has the specified members with the
				1567	specified types. In this case, <code>myNum</code> with a
				1568	type <code>number</code> and <code>myObject</code> with any
				1569	type.</p>
				1570	<p>Notice that the braces are part of the type syntax. For
				1571	example, to denote an <code>Array</code> of objects that
				1572	have a <code>length</code> property, you might write
				1573	<code>Array.<{length}></code>.</p>
				1574	</td>
				1575	<td/>
				1576	</tr>
				1577
				1578	<tr>
				1579	<td>Function Type</td>
				1580	<td>
				1581	<code>{function(string, boolean)}</code><br/>
				1582	A function that takes two arguments (a string and a boolean),
				1583	and has an unknown return value.<br/>
				1584	</td>
				1585	<td>Specifies a function.</td>
				1586	<td/>
				1587	</tr>
				1588
				1589	<tr>
				1590	<td>Function Return Type</td>
				1591	<td>
				1592	<code>{function(): number}</code><br/>
				1593	A function that takes no arguments and returns a number.<br/>
				1594	</td>
				1595	<td>Specifies a function return type.</td>
				1596	<td/>
				1597	</tr>
				1598
				1599	<tr>
				1600	<td>Function <code>this</code> Type</td>
				1601	<td>
				1602	<code>{function(this:goog.ui.Menu, string)}</code><br/>
				1603	A function that takes one argument (a string), and executes
				1604	in the context of a goog.ui.Menu.
				1605	</td>
				1606	<td>Specifies the context type of a function type.</td>
				1607	<td/>
				1608	</tr>
				1609
				1610	<tr>
				1611	<td>Function <code>new</code> Type</td>
				1612	<td>
				1613	<code>{function(new:goog.ui.Menu, string)}</code><br/>
				1614	A constructor that takes one argument (a string), and
				1615	creates a new instance of goog.ui.Menu when called
				1616	with the 'new' keyword.
				1617	</td>
				1618	<td>Specifies the constructed type of a constructor.</td>
				1619	<td/>
				1620	</tr>
				1621
				1622	<tr>
				1623	<td>Variable arguments</td>
				1624	<td>
				1625	<code>{function(string, ...[number]): number}</code><br/>
				1626	A function that takes one argument (a string), and then a
				1627	variable number of arguments that must be numbers.
				1628	</td>
				1629	<td>Specifies variable arguments to a function.</td>
				1630	<td/>
				1631	</tr>
				1632
				1633	<tr>
				1634	<td>
				1635	<a name="var-args-annotation"/>
				1636	Variable arguments (in <code>@param</code> annotations)
				1637	</td>
				1638	<td>
				1639	<code>@param {...number} var_args</code><br/>
				1640	A variable number of arguments to an annotated function.
				1641	</td>
				1642	<td>
				1643	Specifies that the annotated function accepts a variable
				1644	number of arguments.
				1645	</td>
				1646	<td/>
				1647	</tr>
				1648
				1649	<tr>
				1650	<td>Function <a href="#optional">optional arguments</a></td>
				1651	<td>
				1652	<code>{function(?string=, number=)}</code><br/>
				1653	A function that takes one optional, nullable string and one
				1654	optional number as arguments. The <code>=</code> syntax is
				1655	only for <code>function</code> type declarations.
				1656	</td>
				1657	<td>Specifies optional arguments to a function.</td>
				1658	<td/>
				1659	</tr>
				1660
				1661	<tr>
				1662	<td>
				1663	<a name="optional-arg-annotation"/>
				1664	Function <a href="#optional">optional arguments</a>
				1665	(in <code>@param</code> annotations)
				1666	</td>
				1667	<td>
				1668	<code>@param {number=} opt_argument</code><br/>
				1669	An optional parameter of type <code>number</code>.
				1670	</td>
				1671	<td>Specifies that the annotated function accepts an optional
				1672	argument.</td>
				1673	<td/>
				1674	</tr>
				1675
				1676	<tr>
				1677	<td>The ALL type</td>
				1678	<td><code>{*}</code></td>
				1679	<td>Indicates that the variable can take on any type.</td>
				1680	<td/>
				1681	</tr>
				1682
				1683	<tr>
				1684	<td>The UNKNOWN type</td>
				1685	<td><code>{?}</code></td>
				1686	<td>Indicates that the variable can take on any type,
				1687	and the compiler should not type-check any uses of it.</td>
				1688	<td/>
				1689	</tr>
				1690	</tbody>
				1691	</table>
				1692	</SUBSECTION>
				1693	<SUBSECTION title="Types in JavaScript">
				1694	<p/>
				1695	<table border="1" style="border-collapse:collapse" cellpadding="4">
				1696	<thead>
				1697	<tr>
				1698	<th>Type Example</th>
				1699	<th>Value Examples</th>
				1700	<th>Description</th>
				1701	</tr>
				1702	</thead>
				1703	<tbody>
				1704
				1705	<tr>
				1706	<td>number</td>
				1707	<td>
				1708	<CODE_SNIPPET>
				1709	1
				1710	1.0
				1711	-5
				1712	1e5
				1713	Math.PI
				1714	</CODE_SNIPPET>
				1715	</td>
				1716	<td/>
				1717	</tr>
				1718
				1719	<tr>
				1720	<td>Number</td>
				1721	<td>
				1722	<CODE_SNIPPET>
				1723	new Number(true)
				1724	</CODE_SNIPPET>
				1725	</td>
				1726	<td>
				1727	<a href="#Wrapper_objects_for_primitive_types">
				1728	Number object
				1729	</a>
				1730	</td>
				1731	</tr>
				1732
				1733	<tr>
				1734	<td>string</td>
				1735	<td>
				1736	<CODE_SNIPPET>
				1737	'Hello'
				1738	"World"
				1739	String(42)
				1740	</CODE_SNIPPET>
				1741	</td>
				1742	<td>
				1743	String value
				1744	</td>
				1745	</tr>
				1746
				1747	<tr>
				1748	<td>String</td>
				1749	<td>
				1750	<CODE_SNIPPET>
				1751	new String('Hello')
				1752	new String(42)
				1753	</CODE_SNIPPET>
				1754	</td>
				1755	<td>
				1756	<a href="#Wrapper_objects_for_primitive_types">
				1757	String object
				1758	</a>
				1759	</td>
				1760	</tr>
				1761
				1762	<tr>
				1763	<td>boolean</td>
				1764	<td>
				1765	<CODE_SNIPPET>
				1766	true
				1767	false
				1768	Boolean(0)
				1769	</CODE_SNIPPET>
				1770	</td>
				1771	<td>
				1772	Boolean value
				1773	</td>
				1774	</tr>
				1775
				1776	<tr>
				1777	<td>Boolean</td>
				1778	<td>
				1779	<CODE_SNIPPET>
				1780	new Boolean(true)
				1781	</CODE_SNIPPET>
				1782	</td>
				1783	<td>
				1784	<a href="#Wrapper_objects_for_primitive_types">
				1785	Boolean object
				1786	</a>
				1787	</td>
				1788	</tr>
				1789
				1790	<tr>
				1791	<td>RegExp</td>
				1792	<td>
				1793	<CODE_SNIPPET>
				1794	new RegExp('hello')
				1795	/world/g
				1796	</CODE_SNIPPET></td><td>
				1797	</td>
				1798	</tr>
				1799
				1800	<tr>
				1801	<td>Date</td>
				1802	<td>
				1803	<CODE_SNIPPET>
				1804	new Date
				1805	new Date()
				1806	</CODE_SNIPPET></td>
				1807	<td/>
				1808	</tr>
				1809
				1810	<tr>
				1811	<td>
				1812
				1813	null
				1814
				1815	</td>
				1816	<td>
				1817	<CODE_SNIPPET>
				1818	null
				1819	</CODE_SNIPPET>
				1820	</td>
				1821	<td/>
				1822	</tr>
				1823
				1824	<tr>
				1825	<td>
				1826
				1827	undefined
				1828
				1829	</td>
				1830	<td>
				1831	<CODE_SNIPPET>
				1832	undefined
				1833	</CODE_SNIPPET>
				1834	</td>
				1835	<td/>
				1836	</tr>
				1837
				1838	<tr>
				1839	<td>void</td>
				1840	<td>
				1841	<CODE_SNIPPET>
				1842	function f() {
				1843	return;
				1844	}
				1845	</CODE_SNIPPET>
				1846	</td>
				1847	<td>No return value</td>
				1848	</tr>
				1849
				1850	<tr>
				1851	<td>Array</td>
				1852	<td>
				1853	<CODE_SNIPPET>
				1854	['foo', 0.3, null]
				1855	[]
				1856	</CODE_SNIPPET>
				1857	</td>
				1858	<td>Untyped Array</td>
				1859	</tr>
				1860
				1861	<tr>
				1862	<td>Array.<number></td>
				1863	<td>
				1864	<CODE_SNIPPET>
				1865	[11, 22, 33]
				1866	</CODE_SNIPPET>
				1867	</td>
				1868	<td>
				1869	An Array of numbers
				1870	</td>
				1871	</tr>
				1872
				1873	<tr>
				1874	<td>Array.<Array.<string>></td>
				1875	<td>
				1876	<CODE_SNIPPET>
				1877	[['one', 'two', 'three'], ['foo', 'bar']]
				1878	</CODE_SNIPPET>
				1879	</td>
				1880	<td>Array of Arrays of strings</td>
				1881	</tr>
				1882
				1883	<tr>
				1884	<td>Object</td>
				1885	<td>
				1886	<CODE_SNIPPET>
				1887	{}
				1888	{foo: 'abc', bar: 123, baz: null}
				1889	</CODE_SNIPPET>
				1890	</td>
				1891	<td/>
				1892	</tr>
				1893
				1894	<tr>
				1895	<td>Object.<string></td>
				1896	<td>
				1897	<CODE_SNIPPET>
				1898	{'foo': 'bar'}
				1899	</CODE_SNIPPET>
				1900	</td>
				1901	<td>
				1902	An Object in which the values are strings.
				1903	</td>
				1904	</tr>
				1905
				1906	<tr>
				1907	<td>Object.<number, string></td>
				1908	<td>
				1909	<CODE_SNIPPET>
				1910	var obj = {};
				1911	obj[1] = 'bar';
				1912	</CODE_SNIPPET>
				1913	</td>
				1914	<td>
				1915	An Object in which the keys are numbers and the values are
				1916	strings. <p/>Note that in JavaScript, the keys are always
				1917	implicitly converted to strings, so
				1918	<code>obj['1'] == obj[1]</code>.
				1919	So the key will always be a string in for...in loops. But the
				1920	compiler will verify the type of the key when indexing into
				1921	the object.
				1922	</td>
				1923	</tr>
				1924
				1925	<tr>
				1926	<td>Function</td>
				1927	<td>
				1928	<CODE_SNIPPET>
				1929	function(x, y) {
				1930	return x * y;
				1931	}
				1932	</CODE_SNIPPET>
				1933	</td>
				1934	<td>
				1935	<a href="#Wrapper_objects_for_primitive_types">
				1936	Function object
				1937	</a>
				1938	</td>
				1939	</tr>
				1940
				1941	<tr>
				1942	<td>function(number, number): number</td>
				1943	<td>
				1944	<CODE_SNIPPET>
				1945	function(x, y) {
				1946	return x * y;
				1947	}
				1948	</CODE_SNIPPET>
				1949	</td>
				1950	<td>function value</td>
				1951	</tr>
				1952
				1953	<tr>
				1954	<td><a name="constructor-tag">SomeClass</a></td>
				1955	<td>
				1956	<CODE_SNIPPET>
				1957	/** @constructor */
				1958	function SomeClass() {}
				1959
				1960	new SomeClass();
				1961	</CODE_SNIPPET>
				1962	</td>
				1963	<td/>
				1964	</tr>
				1965
				1966	<tr>
				1967	<td>SomeInterface</td>
				1968	<td>
				1969	<CODE_SNIPPET>
				1970	/** @interface */
				1971	function SomeInterface() {}
				1972
				1973	SomeInterface.prototype.draw = function() {};
				1974	</CODE_SNIPPET>
				1975	</td>
				1976	<td/>
				1977	</tr>
				1978
				1979	<tr>
				1980	<td>project.MyClass</td>
				1981	<td>
				1982	<CODE_SNIPPET>
				1983	/** @constructor */
				1984	project.MyClass = function () {}
				1985
				1986	new project.MyClass()
				1987	</CODE_SNIPPET>
				1988	</td>
				1989	<td/>
				1990	</tr>
				1991
				1992	<tr>
				1993	<td>project.MyEnum</td>
				1994	<td>
				1995	<CODE_SNIPPET>
				1996	/** @enum {string} */
				1997	project.MyEnum = {
				1998	/** The color blue. */
				1999	BLUE: '#0000dd',
				2000	/** The color red. */
				2001	RED: '#dd0000'
				2002	};
				2003	</CODE_SNIPPET>
				2004	</td>
				2005	<td><a name="enums">Enumeration</a><p/>
				2006	JSDoc comments on enum values are optional.
				2007	</td>
				2008	</tr>
				2009
				2010	<tr>
				2011	<td>Element</td>
				2012	<td>
				2013	<CODE_SNIPPET>
				2014	document.createElement('div')
				2015	</CODE_SNIPPET>
				2016	</td>
				2017	<td>Elements in the DOM.</td>
				2018	</tr>
				2019
				2020	<tr>
				2021	<td>Node</td>
				2022	<td>
				2023	<CODE_SNIPPET>
				2024	document.body.firstChild
				2025	</CODE_SNIPPET>
				2026	</td>
				2027	<td>Nodes in the DOM.</td>
				2028	</tr>
				2029
				2030	<tr>
				2031	<td>HTMLInputElement</td>
				2032	<td>
				2033	<CODE_SNIPPET>
				2034	htmlDocument.getElementsByTagName('input')[0]
				2035	</CODE_SNIPPET>
				2036	</td>
				2037	<td>A specific type of DOM element.</td>
				2038	</tr>
				2039	</tbody>
				2040	</table>
				2041	</SUBSECTION>
				2042
				2043	<SUBSECTION title="Type Casts">
				2044	<p>In cases where type-checking doesn't accurately infer the type of
				2045	an expression, it is possible to add a type cast comment by adding a
				2046	type annotation comment and enclosing the expression in
				2047	parentheses. The parentheses are required.</p>
				2048
				2049	<CODE_SNIPPET>
				2050	/** @type {number} */ (x)
				2051	</CODE_SNIPPET>
				2052	</SUBSECTION>
				2053
				2054	<SUBSECTION title="Nullable vs. Optional Parameters and Properties">
				2055	<a name="optional"/>
				2056	<p>Because JavaScript is a loosely-typed language, it is very
				2057	important to understand the subtle differences between optional,
				2058	nullable, and undefined function parameters and class
				2059	properties.</p>
				2060
				2061	<p>Instances of classes and interfaces are nullable by default.
				2062	For example, the following declaration</p>
				2063
				2064	<CODE_SNIPPET>
				2065	/**
				2066	* Some class, initialized with a value.
				2067	* @param {Object} value Some value.
				2068	* @constructor
				2069	*/
				2070	function MyClass(value) {
				2071	/**
				2072	* Some value.
				2073	* @type {Object}
				2074	* @private
				2075	*/
				2076	this.myValue_ = value;
				2077	}
				2078	</CODE_SNIPPET>
				2079
				2080	<p>tells the compiler that the <code>myValue_</code> property holds
				2081	either an Object or null. If <code>myValue_</code> must never be
				2082	null, it should be declared like this:</p>
				2083
				2084	<CODE_SNIPPET>
				2085	/**
				2086	* Some class, initialized with a non-null value.
				2087	* @param {!Object} value Some value.
				2088	* @constructor
				2089	*/
				2090	function MyClass(value) {
				2091	/**
				2092	* Some value.
				2093	* @type {!Object}
				2094	* @private
				2095	*/
				2096	this.myValue_ = value;
				2097	}
				2098	</CODE_SNIPPET>
				2099
				2100	<p>This way, if the compiler can determine that somewhere in the code
				2101	<code>MyClass</code> is initialized with a null value, it will issue
				2102	a warning.</p>
				2103
				2104
				2105
				2106	<p>Optional parameters to functions may be undefined at runtime, so if
				2107	they are assigned to class properties, those properties must be
				2108	declared accordingly:</p>
				2109
				2110	<CODE_SNIPPET>
				2111	/**
				2112	* Some class, initialized with an optional value.
				2113	* @param {Object=} opt_value Some value (optional).
				2114	* @constructor
				2115	*/
				2116	function MyClass(opt_value) {
				2117	/**
				2118	* Some value.
				2119	* @type {Object\|undefined}
				2120	* @private
				2121	*/
				2122	this.myValue_ = opt_value;
				2123	}
				2124	</CODE_SNIPPET>
				2125
				2126	<p>This tells the compiler that <code>myValue_</code> may hold an
				2127	Object, null, or remain undefined.</p>
				2128
				2129	<p>Note that the optional parameter <code>opt_value</code> is declared
				2130	to be of type <code>{Object=}</code>, not
				2131	<code>{Object\|undefined}</code>. This is because optional
				2132	parameters may, by definition, be undefined. While there is no harm
				2133	in explicitly declaring an optional parameter as possibly undefined,
				2134	it is both unnecessary and makes the code harder to read.</p>
				2135
				2136	<p>Finally, note that being nullable and being optional are orthogonal
				2137	properties. The following four declarations are all different:</p>
				2138
				2139	<CODE_SNIPPET>
				2140	/**
				2141	* Takes four arguments, two of which are nullable, and two of which are
				2142	* optional.
				2143	* @param {!Object} nonNull Mandatory (must not be undefined), must not be null.
				2144	* @param {Object} mayBeNull Mandatory (must not be undefined), may be null.
				2145	* @param {!Object=} opt_nonNull Optional (may be undefined), but if present,
				2146	* must not be null!
				2147	* @param {Object=} opt_mayBeNull Optional (may be undefined), may be null.
				2148	*/
				2149	function strangeButTrue(nonNull, mayBeNull, opt_nonNull, opt_mayBeNull) {
				2150	// ...
				2151	};
				2152	</CODE_SNIPPET>
				2153	</SUBSECTION>
				2154
				2155	<SUBSECTION title="Typedefs">
				2156	<a name="Typedefs"/>
				2157	<p>Sometimes types can get complicated. A function that accepts
				2158	content for an Element might look like:</p>
				2159
				2160	<CODE_SNIPPET>
				2161	/**
				2162	* @param {string} tagName
				2163	* @param {(string\|Element\|Text\|Array.<Element>\|Array.<Text>)} contents
				2164	* @return {!Element}
				2165	*/
				2166	goog.createElement = function(tagName, contents) {
				2167	...
				2168	};
				2169	</CODE_SNIPPET>
				2170
				2171	<p>You can define commonly used type expressions with a
				2172	<code>@typedef</code> tag. For example,</p>
				2173
				2174	<CODE_SNIPPET>
				2175	/** @typedef {(string\|Element\|Text\|Array.<Element>\|Array.<Text>)} */
				2176	goog.ElementContent;
				2177
				2178	/**
				2179	* @param {string} tagName
				2180	* @param {goog.ElementContent} contents
				2181	* @return {!Element}
				2182	*/
				2183	goog.createElement = function(tagName, contents) {
				2184	...
				2185	};
				2186	</CODE_SNIPPET>
				2187	</SUBSECTION>
				2188
				2189	<SUBSECTION title="Template types">
				2190	<a name="Template_types"/>
				2191	<p>The compiler has limited support for template types. It can only
				2192	infer the type of <code>this</code> inside an anonymous function
				2193	literal from the type of the <code>this</code> argument and whether the
				2194	<code>this</code> argument is missing.</p>
				2195
				2196	<CODE_SNIPPET>
				2197	/**
				2198	* @param {function(this:T, ...)} fn
				2199	* @param {T} thisObj
				2200	* @param {...*} var_args
				2201	* @template T
				2202	*/
				2203	goog.bind = function(fn, thisObj, var_args) {
				2204	...
				2205	};
				2206	// Possibly generates a missing property warning.
				2207	goog.bind(function() { this.someProperty; }, new SomeClass());
				2208	// Generates an undefined this warning.
				2209	goog.bind(function() { this.someProperty; });
				2210	</CODE_SNIPPET>
				2211	</SUBSECTION>
				2212	</BODY>
				2213	</STYLEPOINT>
				2214
				2215	<STYLEPOINT title="Comments">
				2216	<SUMMARY>Use JSDoc</SUMMARY>
				2217	<BODY>
				2218	<p>
				2219	We follow the
				2220	<a href="cppguide.html#Comments">
				2221	C++ style for comments</a> in spirit.
				2222	</p>
				2223
				2224	<p>All files, classes, methods and properties should be documented with
				2225	<a href="https://code.google.com/p/jsdoc-toolkit/">JSDoc</a>
				2226	comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a>
				2227	and <a href="#JsTypes">types</a>. Textual descriptions for properties,
				2228	methods, method parameters and method return values should be included
				2229	unless obvious from the property, method, or parameter name.
				2230	</p>
				2231
				2232	<p>Inline comments should be of the <code>//</code> variety.</p>
				2233
				2234	<p>Complete sentences are recommended but not required.
				2235	Complete sentences should use appropriate capitalization
				2236	and punctuation.</p>
				2237
				2238	<SUBSECTION title="Comment Syntax">
				2239	<p>The JSDoc syntax is based on
				2240	<a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
				2241	JavaDoc</a>. Many tools extract metadata from JSDoc comments to
				2242	perform code validation and optimizations. These comments must be
				2243	well-formed.</p>
				2244
				2245	<CODE_SNIPPET>
				2246	/**
				2247	* A JSDoc comment should begin with a slash and 2 asterisks.
				2248	* Inline tags should be enclosed in braces like {@code this}.
				2249	* @desc Block tags should always start on their own line.
				2250	*/
				2251	</CODE_SNIPPET>
				2252	</SUBSECTION>
				2253
				2254	<SUBSECTION title="JSDoc Indentation">
				2255	<p>If you have to line break a block tag, you should treat this as
				2256	breaking a code statement and indent it four spaces.</p>
				2257
				2258	<CODE_SNIPPET>
				2259	/**
				2260	* Illustrates line wrapping for long param/return descriptions.
				2261	* @param {string} foo This is a param with a description too long to fit in
				2262	* one line.
				2263	* @return {number} This returns something that has a description too long to
				2264	* fit in one line.
				2265	*/
				2266	project.MyClass.prototype.method = function(foo) {
				2267	return 5;
				2268	};
				2269	</CODE_SNIPPET>
				2270
				2271	<p>You should not indent the <code>@fileoverview</code> command. You do not have to
				2272	indent the <code>@desc</code> command.</p>
				2273
				2274	<p>Even though it is not preferred, it is also acceptable to line up
				2275	the description.</p>
				2276
				2277	<CODE_SNIPPET>
				2278	/**
				2279	* This is NOT the preferred indentation method.
				2280	* @param {string} foo This is a param with a description too long to fit in
				2281	* one line.
				2282	* @return {number} This returns something that has a description too long to
				2283	* fit in one line.
				2284	*/
				2285	project.MyClass.prototype.method = function(foo) {
				2286	return 5;
				2287	};
				2288	</CODE_SNIPPET>
				2289	</SUBSECTION>
				2290
				2291	<SUBSECTION title="HTML in JSDoc">
				2292	<p>Like JavaDoc, JSDoc supports many HTML tags, like <code>,
				2293	<pre>, <tt>, <strong>, <ul>, <ol>,
				2294	<li>, <a>, and others.</p>
				2295
				2296	<p>This means that plaintext formatting is not respected. So, don't
				2297	rely on whitespace to format JSDoc:</p>
				2298
				2299	<BAD_CODE_SNIPPET>
				2300	/**
				2301	* Computes weight based on three factors:
				2302	* items sent
				2303	* items received
				2304	* last timestamp
				2305	*/
				2306	</BAD_CODE_SNIPPET>
				2307
				2308	<p>It'll come out like this:</p>
				2309
				2310	<BAD_CODE_SNIPPET>
				2311	Computes weight based on three factors: items sent items received last timestamp
				2312	</BAD_CODE_SNIPPET>
				2313
				2314	<p>Instead, do this:</p>
				2315
				2316	<CODE_SNIPPET>
				2317	/**
				2318	* Computes weight based on three factors:
				2319	* <ul>
				2320	* <li>items sent
				2321	* <li>items received
				2322	* <li>last timestamp
				2323	* </ul>
				2324	*/
				2325	</CODE_SNIPPET>
				2326
				2327	The <a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
				2328	JavaDoc</a> style guide is a useful resource on how to write
				2329	well-formed doc comments.
				2330	</SUBSECTION>
				2331
				2332	<SUBSECTION title="Top/File-Level Comments">
				2333	<p>
				2334
				2335	A <a href="copyright.html">copyright notice</a> and author information are optional.
				2336	File overviews are generally recommended whenever a file consists of
				2337	more than a single class definition. The top level comment is
				2338	designed to orient readers unfamiliar with the code to what is in
				2339	this file. If present, it should provide a description of the
				2340	file's contents and any dependencies or compatibility information.
				2341	As an example:
				2342	</p>
				2343
				2344	<CODE_SNIPPET>
				2345	/**
				2346	* @fileoverview Description of file, its uses and information
				2347	* about its dependencies.
				2348	*/
				2349	</CODE_SNIPPET>
				2350
				2351
				2352	</SUBSECTION>
				2353
				2354	<SUBSECTION title="Class Comments">
				2355	<p>Classes must be documented with a description and a
				2356	<a href="#constructor-tag">type tag that
				2357	identifies the constructor</a>.
				2358	</p>
				2359
				2360	<CODE_SNIPPET>
				2361	/**
				2362	* Class making something fun and easy.
				2363	* @param {string} arg1 An argument that makes this more interesting.
				2364	* @param {Array.<number>} arg2 List of numbers to be processed.
				2365	* @constructor
				2366	* @extends {goog.Disposable}
				2367	*/
				2368	project.MyClass = function(arg1, arg2) {
				2369	// ...
				2370	};
				2371	goog.inherits(project.MyClass, goog.Disposable);
				2372	</CODE_SNIPPET>
				2373	</SUBSECTION>
				2374
				2375	<SUBSECTION title="Method and Function Comments">
				2376	<p>Parameter and return types should be documented. The method
				2377	description may be omitted if it is obvious from the parameter
				2378	or return type descriptions. Method descriptions should start
				2379	with a sentence written in the third person declarative voice.</p>
				2380	<CODE_SNIPPET>
				2381	/**
				2382	* Operates on an instance of MyClass and returns something.
				2383	* @param {project.MyClass} obj Instance of MyClass which leads to a long
				2384	* comment that needs to be wrapped to two lines.
				2385	* @return {boolean} Whether something occurred.
				2386	*/
				2387	function PR_someMethod(obj) {
				2388	// ...
				2389	}
				2390	</CODE_SNIPPET>
				2391	</SUBSECTION>
				2392
				2393	<SUBSECTION title="Property Comments">
				2394	<CODE_SNIPPET>
				2395	/** @constructor */
				2396	project.MyClass = function() {
				2397	/**
				2398	* Maximum number of things per pane.
				2399	* @type {number}
				2400	*/
				2401	this.someProperty = 4;
				2402	}
				2403	</CODE_SNIPPET>
				2404	</SUBSECTION>
				2405
				2406	<SUBSECTION title="JSDoc Tag Reference">
				2407	<a name="JSDoc_Tag_Reference"/>
				2408	<p/>
				2409	<table border="1" style="border-collapse:collapse" cellpadding="4">
				2410	<thead>
				2411	<tr>
				2412	<th>Tag</th>
				2413	<th>Template & Examples</th>
				2414	<th>Description</th>
				2415	</tr>
				2416	</thead>
				2417	<tbody>
				2418	<tr>
				2419	<td>
				2420	<a name="tag-author">@author</a>
				2421
				2422	</td>
				2423	<td>
				2424	<code>@author username@google.com (first last)</code>
				2425	<p><i>For example:</i></p>
				2426	<CODE_SNIPPET>
				2427	/**
				2428	* @fileoverview Utilities for handling textareas.
				2429	* @author kuth@google.com (Uthur Pendragon)
				2430	*/
				2431	</CODE_SNIPPET>
				2432	</td>
				2433	<td>
				2434	Document the author of a file or the owner of a test,
				2435	generally only used in the <code>@fileoverview</code> comment.
				2436
				2437	</td>
				2438	</tr>
				2439
				2440
				2441
				2442	<tr>
				2443	<td><a name="tag-code">@code</a></td>
				2444	<td>
				2445	<code>{@code ...}</code>
				2446	<p><i>For example:</i></p>
				2447	<CODE_SNIPPET>
				2448	/**
				2449	* Moves to the next position in the selection.
				2450	* Throws {@code goog.iter.StopIteration} when it
				2451	* passes the end of the range.
				2452	* @return {Node} The node at the next position.
				2453	*/
				2454	goog.dom.RangeIterator.prototype.next = function() {
				2455	// ...
				2456	};
				2457	</CODE_SNIPPET>
				2458	</td>
				2459	<td>
				2460	Indicates that a term in a JSDoc description is code so it may
				2461	be correctly formatted in generated documentation.
				2462	</td>
				2463	</tr>
				2464
				2465	<tr>
				2466	<td><a name="tag-const">@const</a></td>
				2467	<td>
				2468	<code>@const</code><br/>
				2469	<code>@const {type}</code>
				2470	<p><i>For example:</i></p>
				2471	<CODE_SNIPPET>
				2472	/** @const */ var MY_BEER = 'stout';
				2473
				2474	/**
				2475	* My namespace's favorite kind of beer.
				2476	* @const {string}
				2477	*/
				2478	mynamespace.MY_BEER = 'stout';
				2479
				2480	/** @const */ MyClass.MY_BEER = 'stout';
				2481
				2482	/**
				2483	* Initializes the request.
				2484	* @const
				2485	*/
				2486	mynamespace.Request.prototype.initialize = function() {
				2487	// This method cannot be overridden in a subclass.
				2488	};
				2489	</CODE_SNIPPET>
				2490	</td>
				2491	<td>
				2492	<p>Marks a variable (or property) as read-only and suitable
				2493	for inlining.</p>
				2494
				2495	<p>A <code>@const</code> variable is an immutable pointer to
				2496	a value. If a variable or property marked as
				2497	<code>@const</code> is overwritten, JSCompiler will give
				2498	warnings.</p>
				2499
				2500	<p>The type declaration of a constant value can be omitted
				2501	if it can be clearly inferred. An additional comment about
				2502	the variable is optional.</p>
				2503
				2504	<p>When <code>@const</code> is applied to a method, it
				2505	implies the method is not only not overwritable, but also
				2506	that the method is <em>finalized</em> —
				2507	not overridable in subclasses.</p>
				2508
				2509	<p>For more on <code>@const</code>, see the
				2510	<a href="#Constants">Constants</a> section.</p>
				2511
				2512	</td>
				2513	</tr>
				2514
				2515	<tr>
				2516	<td><a name="tag-constructor">@constructor</a></td>
				2517	<td>
				2518	<code>@constructor</code>
				2519	<p><i>For example:</i></p>
				2520	<CODE_SNIPPET>
				2521	/**
				2522	* A rectangle.
				2523	* @constructor
				2524	*/
				2525	function GM_Rect() {
				2526	...
				2527	}
				2528	</CODE_SNIPPET>
				2529	</td>
				2530	<td>
				2531	Used in a class's documentation to indicate the constructor.
				2532	</td>
				2533	</tr>
				2534
				2535	<tr>
				2536	<td><a name="tag-define">@define</a></td>
				2537	<td>
				2538	<code>@define {Type} description</code>
				2539	<p><i>For example:</i></p>
				2540	<CODE_SNIPPET>
				2541	/** @define {boolean} */
				2542	var TR_FLAGS_ENABLE_DEBUG = true;
				2543
				2544	/**
				2545	* @define {boolean} Whether we know at compile-time that
				2546	* the browser is IE.
				2547	*/
				2548	goog.userAgent.ASSUME_IE = false;
				2549	</CODE_SNIPPET>
				2550	</td>
				2551	<td>
				2552	Indicates a constant that can be overridden by the compiler at
				2553	compile-time. In the example, the compiler flag
				2554	<code>--define='goog.userAgent.ASSUME_IE=true'</code>
				2555	could be specified in the BUILD file to indicate that the
				2556	constant <code>goog.userAgent.ASSUME_IE</code> should be replaced
				2557	with <code>true</code>.
				2558	</td>
				2559	</tr>
				2560
				2561	<tr>
				2562	<td><a name="tag-deprecated">@deprecated</a></td>
				2563	<td>
				2564	<code>@deprecated Description</code>
				2565	<p><i>For example:</i></p>
				2566	<CODE_SNIPPET>
				2567	/**
				2568	* Determines whether a node is a field.
				2569	* @return {boolean} True if the contents of
				2570	* the element are editable, but the element
				2571	* itself is not.
				2572	* @deprecated Use isField().
				2573	*/
				2574	BN_EditUtil.isTopEditableField = function(node) {
				2575	// ...
				2576	};
				2577	</CODE_SNIPPET>
				2578	</td>
				2579	<td>
				2580	Used to tell that a function, method or property should not be
				2581	used any more. Always provide instructions on what callers
				2582	should use instead.
				2583	</td>
				2584	</tr>
				2585
				2586	<tr>
				2587	<td><a name="tag-dict">@dict</a></td>
				2588	<td>
				2589	<code>@dict Description</code>
				2590	<p><i>For example:</i></p>
				2591	<CODE_SNIPPET>
				2592	/**
				2593	* @constructor
				2594	* @dict
				2595	*/
				2596	function Foo(x) {
				2597	this['x'] = x;
				2598	}
				2599	var obj = new Foo(123);
				2600	var num = obj.x; // warning
				2601
				2602	(/** @dict */ { x: 1 }).x = 123; // warning
				2603	</CODE_SNIPPET>
				2604	</td>
				2605	<td>
				2606	When a constructor (<code>Foo</code> in the example) is
				2607	annotated with <code>@dict</code>, you can only use the
				2608	bracket notation to access the properties of <code>Foo</code>
				2609	objects.
				2610	The annotation can also be used directly on object literals.
				2611	</td>
				2612	</tr>
				2613
				2614	<tr>
				2615	<td><a name="tag-enum">@enum</a></td>
				2616	<td>
				2617	<code>@enum {Type}</code>
				2618	<p><i>For example:</i></p>
				2619	<CODE_SNIPPET>
				2620	/**
				2621	* Enum for tri-state values.
				2622	* @enum {number}
				2623	*/
				2624	project.TriState = {
				2625	TRUE: 1,
				2626	FALSE: -1,
				2627	MAYBE: 0
				2628	};
				2629	</CODE_SNIPPET>
				2630	</td>
				2631	</tr>
				2632
				2633	<tr>
				2634	<td><a name="tag-export">@export</a></td>
				2635	<td>
				2636	<code>@export</code>
				2637	<p><i>For example:</i></p>
				2638	<CODE_SNIPPET>
				2639	/** @export */
				2640	foo.MyPublicClass.prototype.myPublicMethod = function() {
				2641	// ...
				2642	};
				2643	</CODE_SNIPPET>
				2644	</td>
				2645	<td>
				2646	<p>Given the code on the left, when the compiler is run with
				2647	the <code>--generate_exports</code> flag, it will generate the
				2648	code:</p>
				2649	<CODE_SNIPPET>
				2650	goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod',
				2651	foo.MyPublicClass.prototype.myPublicMethod);
				2652	</CODE_SNIPPET>
				2653	<p>which will export the symbols to uncompiled code.
				2654	Code that uses the <code>@export</code> annotation must either</p>
				2655	<ol>
				2656	<li>include <code>//javascript/closure/base.js</code>, or</li>
				2657	<li>define both <code>goog.exportSymbol</code> and
				2658	<code>goog.exportProperty</code> with the same method
				2659	signature in their own codebase.</li>
				2660	</ol>
				2661	</td>
				2662	</tr>
				2663
				2664	<tr>
				2665	<td><a name="tag-expose">@expose</a></td>
				2666	<td>
				2667	<code>@expose</code>
				2668	<p><i>For example:</i></p>
				2669	<CODE_SNIPPET>
				2670	/** @expose */
				2671	MyClass.prototype.exposedProperty = 3;
				2672	</CODE_SNIPPET>
				2673	</td>
				2674	<td>
				2675	<p>
				2676	Declares an exposed property. Exposed properties
				2677	will not be removed, or renamed, or collapsed,
				2678	or optimized in any way by the compiler. No properties
				2679	with the same name will be able to be optimized either.
				2680	</p>
				2681
				2682	<p>
				2683	<code>@expose</code> should never be used in library code,
				2684	because it will prevent that property from ever getting
				2685	removed.
				2686	</p>
				2687	</td>
				2688	</tr>
				2689
				2690	<tr>
				2691	<td><a name="tag-extends">@extends</a></td>
				2692	<td>
				2693	<code>
				2694	@extends Type<br/>
				2695	@extends {Type}
				2696	</code>
				2697	<p><i>For example:</i></p>
				2698	<CODE_SNIPPET>
				2699	/**
				2700	* Immutable empty node list.
				2701	* @constructor
				2702	* @extends goog.ds.BasicNodeList
				2703	*/
				2704	goog.ds.EmptyNodeList = function() {
				2705	...
				2706	};
				2707	</CODE_SNIPPET>
				2708	</td>
				2709	<td>
				2710	Used with <code>@constructor</code> to indicate that a class
				2711	inherits from another class. Curly braces around the type are
				2712	optional.
				2713	</td>
				2714	</tr>
				2715
				2716	<tr>
				2717	<td><a name="tag-externs">@externs</a></td>
				2718	<td>
				2719	<code>@externs</code>
				2720	<p><i>For example:</i></p>
				2721	<CODE_SNIPPET>
				2722	/**
				2723	* @fileoverview This is an externs file.
				2724	* @externs
				2725	*/
				2726
				2727	var document;
				2728	</CODE_SNIPPET>
				2729	</td>
				2730	<td>
				2731	<p>
				2732	Declares an
				2733
				2734	externs file.
				2735	</p>
				2736
				2737
				2738	</td>
				2739	</tr>
				2740
				2741	<tr>
				2742	<td><a name="tag-fileoverview">@fileoverview</a></td>
				2743	<td>
				2744	<code>@fileoverview Description</code>
				2745	<p><i>For example:</i></p>
				2746	<CODE_SNIPPET>
				2747	/**
				2748	* @fileoverview Utilities for doing things that require this very long
				2749	* but not indented comment.
				2750	* @author kuth@google.com (Uthur Pendragon)
				2751	*/
				2752	</CODE_SNIPPET>
				2753	</td>
				2754	<td>Makes the comment block provide file level information.</td>
				2755	</tr>
				2756
				2757	<tr>
				2758	<td><a name="tag-implements">@implements</a></td>
				2759	<td>
				2760	<code>
				2761	@implements Type<br/>
				2762	@implements {Type}
				2763	</code>
				2764	<p><i>For example:</i></p>
				2765	<CODE_SNIPPET>
				2766	/**
				2767	* A shape.
				2768	* @interface
				2769	*/
				2770	function Shape() {};
				2771	Shape.prototype.draw = function() {};
				2772
				2773	/**
				2774	* @constructor
				2775	* @implements {Shape}
				2776	*/
				2777	function Square() {};
				2778	Square.prototype.draw = function() {
				2779	...
				2780	};
				2781	</CODE_SNIPPET>
				2782	</td>
				2783	<td>
				2784	Used with <code>@constructor</code> to indicate that a class
				2785	implements an interface. Curly braces around the type are
				2786	optional.
				2787	</td>
				2788	</tr>
				2789
				2790	<tr>
				2791	<td><a name="tag-inheritDoc">@inheritDoc</a></td>
				2792	<td>
				2793	<code>@inheritDoc</code>
				2794	<p><i>For example:</i></p>
				2795	<CODE_SNIPPET>
				2796	/** @inheritDoc */
				2797	project.SubClass.prototype.toString() {
				2798	// ...
				2799	};
				2800	</CODE_SNIPPET>
				2801	</td>
				2802	<td>
				2803	<p style="font-weight:bold">Deprecated. Use
				2804	<code>@override</code> instead.</p>
				2805
				2806	Indicates that a method or property of a subclass
				2807	intentionally hides a method or property of the superclass,
				2808	and has exactly the same documentation. Notice that
				2809	<code>@inheritDoc</code> implies <code>@override</code>
				2810	</td>
				2811	</tr>
				2812
				2813	<tr>
				2814	<td><a name="tag-interface">@interface</a></td>
				2815	<td>
				2816	<code>@interface</code>
				2817	<p><i>For example:</i></p>
				2818	<CODE_SNIPPET>
				2819	/**
				2820	* A shape.
				2821	* @interface
				2822	*/
				2823	function Shape() {};
				2824	Shape.prototype.draw = function() {};
				2825
				2826	/**
				2827	* A polygon.
				2828	* @interface
				2829	* @extends {Shape}
				2830	*/
				2831	function Polygon() {};
				2832	Polygon.prototype.getSides = function() {};
				2833	</CODE_SNIPPET>
				2834	</td>
				2835	<td>
				2836	Used to indicate that the function defines an interface.
				2837	</td>
				2838	</tr>
				2839
				2840	<tr>
				2841	<td><a name="tag-lends">@lends</a></td>
				2842	<td>
				2843	<code>@lends objectName</code><br/>
				2844	<code>@lends {objectName}</code>
				2845	<p><i>For example:</i></p>
				2846	<CODE_SNIPPET>
				2847	goog.object.extend(
				2848	Button.prototype,
				2849	/** @lends {Button.prototype} */ {
				2850	isButton: function() { return true; }
				2851	});
				2852	</CODE_SNIPPET>
				2853	</td>
				2854	<td>
				2855	Indicates that the keys of an object literal should
				2856	be treated as properties of some other object. This annotation
				2857	should only appear on object literals.<p/>
				2858
				2859	Notice that the name in braces is not a type name like
				2860	in other annotations. It's an object name. It names
				2861	the object on which the properties are "lent".
				2862	For example, <code>@type {Foo}</code> means "an instance of Foo",
				2863	but <code>@lends {Foo}</code> means "the constructor Foo".<p/>
				2864
				2865	The <a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
				2866	JSDoc Toolkit docs</a> have more information on this
				2867	annotation.
				2868	</td>
				2869	</tr>
				2870
				2871	<tr>
				2872	<td><a name="tag-license">@license</a> or
				2873	<a name="tag-preserve">@preserve</a></td>
				2874	<td>
				2875	<code>@license Description</code>
				2876	<p><i>For example:</i></p>
				2877	<CODE_SNIPPET>
				2878	/**
				2879	* @preserve Copyright 2009 SomeThirdParty.
				2880	* Here is the full license text and copyright
				2881	* notice for this file. Note that the notice can span several
				2882	* lines and is only terminated by the closing star and slash:
				2883	*/
				2884	</CODE_SNIPPET>
				2885	</td>
				2886	<td>
				2887	Anything marked by <code>@license</code> or
				2888	<code>@preserve</code> will be retained by the compiler and
				2889	output at the top of the compiled code for that file. This
				2890	annotation allows important notices (such as legal licenses or
				2891	copyright text) to survive compilation unchanged. Line breaks
				2892	are preserved.
				2893	</td>
				2894	</tr>
				2895
				2896
				2897
				2898
				2899
				2900	<tr>
				2901	<td><a name="tag-noalias">@noalias</a></td>
				2902	<td>
				2903	<code>@noalias</code>
				2904	<p><i>For example:</i></p>
				2905	<CODE_SNIPPET>
				2906	/** @noalias */
				2907	function Range() {}
				2908	</CODE_SNIPPET>
				2909	</td>
				2910	<td>
				2911	Used in an externs file to indicate to the compiler that the
				2912	variable or function should not be aliased as part of the
				2913	alias externals pass of the compiler.
				2914	</td>
				2915	</tr>
				2916
				2917	<tr>
				2918	<td><a name="tag-nocompile">@nocompile</a></td>
				2919	<td>
				2920	<code>@nocompile</code>
				2921	<p><i>For example:</i></p>
				2922	<CODE_SNIPPET>
				2923	/** @nocompile */
				2924
				2925	// JavaScript code
				2926	</CODE_SNIPPET>
				2927	</td>
				2928	<td>
				2929	Used at the top of a file to tell the compiler to parse this
				2930	file but not compile it.
				2931	Code that is not meant for compilation and should be omitted
				2932	from compilation tests (such as bootstrap code) uses this
				2933	annotation.
				2934	Use sparingly.
				2935	</td>
				2936	</tr>
				2937
				2938	<tr>
				2939	<td><a name="tag-nosideeffects">@nosideeffects</a></td>
				2940	<td>
				2941	<code>@nosideeffects</code>
				2942	<p><i>For example:</i></p>
				2943	<CODE_SNIPPET>
				2944	/** @nosideeffects */
				2945	function noSideEffectsFn1() {
				2946	// ...
				2947	}
				2948
				2949	/** @nosideeffects */
				2950	var noSideEffectsFn2 = function() {
				2951	// ...
				2952	};
				2953
				2954	/** @nosideeffects */
				2955	a.prototype.noSideEffectsFn3 = function() {
				2956	// ...
				2957	};
				2958	</CODE_SNIPPET>
				2959	</td>
				2960	<td>
				2961	This annotation can be used as part of function and
				2962	constructor declarations to indicate that calls to the
				2963	declared function have no side-effects. This annotation
				2964	allows the compiler to remove calls to these functions if the
				2965	return value is not used.
				2966	</td>
				2967	</tr>
				2968
				2969	<tr>
				2970	<td><a name="tag-override">@override</a></td>
				2971	<td>
				2972	<code>@override</code>
				2973	<p><i>For example:</i></p>
				2974	<CODE_SNIPPET>
				2975	/**
				2976	* @return {string} Human-readable representation of project.SubClass.
				2977	* @override
				2978	*/
				2979	project.SubClass.prototype.toString = function() {
				2980	// ...
				2981	};
				2982	</CODE_SNIPPET>
				2983	</td>
				2984	<td>
				2985	Indicates that a method or property of a subclass
				2986	intentionally hides a method or property of the superclass. If
				2987	no other documentation is included, the method or property
				2988	also inherits documentation from its superclass.
				2989	</td>
				2990	</tr>
				2991
				2992	<tr>
				2993	<td><a name="tag-param">@param</a></td>
				2994	<td>
				2995	<code>@param {Type} varname Description</code>
				2996	<p><i>For example:</i></p>
				2997	<CODE_SNIPPET>
				2998	/**
				2999	* Queries a Baz for items.
				3000	* @param {number} groupNum Subgroup id to query.
				3001	* @param {string\|number\|null} term An itemName,
				3002	* or itemId, or null to search everything.
				3003	*/
				3004	goog.Baz.prototype.query = function(groupNum, term) {
				3005	// ...
				3006	};
				3007	</CODE_SNIPPET>
				3008	</td>
				3009	<td>
				3010	Used with method, function and constructor calls to document
				3011	the arguments of a function.<p/>
				3012
				3013	<a href="#JsTypes">Type</a>
				3014	names must be enclosed in curly braces. If the type
				3015	is omitted, the compiler will not type-check the parameter.
				3016	</td>
				3017	</tr>
				3018
				3019	<tr>
				3020	<td><a name="tag-private">@private</a></td>
				3021	<td>
				3022	<code>@private</code><br/>
				3023	<code>@private {type}</code>
				3024	<p><i>For example:</i></p>
				3025	<CODE_SNIPPET>
				3026	/**
				3027	* Handlers that are listening to this logger.
				3028	* @private {!Array.<Function>}
				3029	*/
				3030	this.handlers_ = [];
				3031	</CODE_SNIPPET>
				3032	</td>
				3033	<td>
				3034	Used in conjunction with a trailing underscore on the method
				3035	or property name to indicate that the member is
				3036	<a href="#Visibility__private_and_protected_fields_">private</a> and final.
				3037	</td>
				3038	</tr>
				3039
				3040	<tr>
				3041	<td><a name="tag-protected">@protected</a></td>
				3042	<td>
				3043	<code>@protected</code><br/>
				3044	<code>@protected {type}</code>
				3045	<p><i>For example:</i></p>
				3046	<CODE_SNIPPET>
				3047	/**
				3048	* Sets the component's root element to the given element.
				3049	* @param {Element} element Root element for the component.
				3050	* @protected
				3051	*/
				3052	goog.ui.Component.prototype.setElementInternal = function(element) {
				3053	// ...
				3054	};
				3055	</CODE_SNIPPET>
				3056	</td>
				3057	<td>
				3058	Used to indicate that the member or property is
				3059	<a href="#Visibility__private_and_protected_fields_">protected</a>.
				3060	Should be used in conjunction with names with no trailing
				3061	underscore.
				3062	</td>
				3063	</tr>
				3064
				3065	<tr>
				3066	<td><a name="tag-public">@public</a></td>
				3067	<td>
				3068	<code>@public</code><br/>
				3069	<code>@public {type}</code>
				3070	<p><i>For example:</i></p>
				3071	<CODE_SNIPPET>
				3072	/**
				3073	* Whether to cancel the event in internal capture/bubble processing.
				3074	* @public {boolean}
				3075	* @suppress {visiblity} Referencing this outside this package is strongly
				3076	* discouraged.
				3077	*/
				3078	goog.events.Event.prototype.propagationStopped_ = false;
				3079	</CODE_SNIPPET>
				3080	</td>
				3081	<td>
				3082	Used to indicate that the member or property is public. Variables and
				3083	properties are public by default, so this annotation is rarely necessary.
				3084	Should only be used in legacy code that cannot be easily changed to
				3085	override the visibility of members that were named as private variables.
				3086	</td>
				3087	</tr>
				3088
				3089	<tr>
				3090	<td><a name="tag-return">@return</a></td>
				3091	<td>
				3092	<code>@return {Type} Description</code>
				3093	<p><i>For example:</i></p>
				3094	<CODE_SNIPPET>
				3095	/**
				3096	* @return {string} The hex ID of the last item.
				3097	*/
				3098	goog.Baz.prototype.getLastId = function() {
				3099	// ...
				3100	return id;
				3101	};
				3102	</CODE_SNIPPET>
				3103	</td>
				3104	<td>
				3105	Used with method and function calls to document the return
				3106	type. When writing descriptions for boolean parameters,
				3107	prefer "Whether the component is visible" to "True if the
				3108	component is visible, false otherwise". If there is no return
				3109	value, do not use an <code>@return</code> tag.<p/>
				3110
				3111	<a href="#JsTypes">Type</a>
				3112	names must be enclosed in curly braces. If the type
				3113	is omitted, the compiler will not type-check the return value.
				3114	</td>
				3115	</tr>
				3116
				3117	<tr>
				3118	<td><a name="tag-see">@see</a></td>
				3119	<td>
				3120	<code>@see Link</code>
				3121	<p><i>For example:</i></p>
				3122	<CODE_SNIPPET>
				3123	/**
				3124	* Adds a single item, recklessly.
				3125	* @see #addSafely
				3126	* @see goog.Collect
				3127	* @see goog.RecklessAdder#add
				3128	...
				3129	</CODE_SNIPPET>
				3130	</td>
				3131	<td>Reference a lookup to another class function or method.</td>
				3132	</tr>
				3133
				3134	<tr>
				3135	<td><a name="tag-struct">@struct</a></td>
				3136	<td>
				3137	<code>@struct Description</code>
				3138	<p><i>For example:</i></p>
				3139	<CODE_SNIPPET>
				3140	/**
				3141	* @constructor
				3142	* @struct
				3143	*/
				3144	function Foo(x) {
				3145	this.x = x;
				3146	}
				3147	var obj = new Foo(123);
				3148	var num = obj['x']; // warning
				3149	obj.y = "asdf"; // warning
				3150
				3151	Foo.prototype = /** @struct */ {
				3152	method1: function() {}
				3153	};
				3154	Foo.prototype.method2 = function() {}; // warning
				3155	</CODE_SNIPPET>
				3156	</td>
				3157	<td>
				3158	When a constructor (<code>Foo</code> in the example) is
				3159	annotated with <code>@struct</code>, you can only use the dot
				3160	notation to access the properties of <code>Foo</code> objects.
				3161	Also, you cannot add new properties to <code>Foo</code>
				3162	objects after they have been created.
				3163	The annotation can also be used directly on object literals.
				3164	</td>
				3165	</tr>
				3166
				3167	<tr>
				3168	<td><a name="tag-supported">@supported</a></td>
				3169	<td>
				3170	<code>@supported Description</code>
				3171	<p><i>For example:</i></p>
				3172	<CODE_SNIPPET>
				3173	/**
				3174	* @fileoverview Event Manager
				3175	* Provides an abstracted interface to the
				3176	* browsers' event systems.
				3177	* @supported So far tested in IE6 and FF1.5
				3178	*/
				3179	</CODE_SNIPPET>
				3180	</td>
				3181	<td>
				3182	Used in a fileoverview to indicate what browsers are supported
				3183	by the file.
				3184	</td>
				3185	</tr>
				3186
				3187	<tr>
				3188	<td><a name="tag-suppress">@suppress</a></td>
				3189	<td>
				3190	<code>
				3191	@suppress {warning1\|warning2}
				3192	</code>
				3193	<code>
				3194	@suppress {warning1,warning2}
				3195	</code>
				3196	<p><i>For example:</i></p>
				3197	<CODE_SNIPPET>
				3198	/**
				3199	* @suppress {deprecated}
				3200	*/
				3201	function f() {
				3202	deprecatedVersionOfF();
				3203	}
				3204	</CODE_SNIPPET>
				3205	</td>
				3206	<td>
				3207	Suppresses warnings from tools. Warning categories are
				3208	separated by <code>\|</code> or <code>,</code>.
				3209
				3210	</td>
				3211	</tr>
				3212
				3213	<tr>
				3214	<td><a name="tag-template">@template</a></td>
				3215	<td>
				3216	<code>@template</code>
				3217	<p><i>For example:</i></p>
				3218	<CODE_SNIPPET>
				3219	/**
				3220	* @param {function(this:T, ...)} fn
				3221	* @param {T} thisObj
				3222	* @param {...*} var_args
				3223	* @template T
				3224	*/
				3225	goog.bind = function(fn, thisObj, var_args) {
				3226	...
				3227	};
				3228	</CODE_SNIPPET>
				3229	</td>
				3230	<td>
				3231	This annotation can be used to declare a
				3232	<a href="#Template_types">template typename</a>.
				3233	</td>
				3234	</tr>
				3235
				3236	<tr>
				3237	<td><a name="tag-this">@this</a></td>
				3238	<td>
				3239	<code>
				3240	@this Type<br/>
				3241	@this {Type}
				3242	</code>
				3243	<p><i>For example:</i></p>
				3244	<CODE_SNIPPET>
				3245	pinto.chat.RosterWidget.extern('getRosterElement',
				3246	/**
				3247	* Returns the roster widget element.
				3248	* @this pinto.chat.RosterWidget
				3249	* @return {Element}
				3250	*/
				3251	function() {
				3252	return this.getWrappedComponent_().getElement();
				3253	});
				3254	</CODE_SNIPPET>
				3255	</td>
				3256	<td>
				3257	The type of the object in whose context a particular method is
				3258	called. Required when the <code>this</code> keyword is referenced
				3259	from a function that is not a prototype method.
				3260	</td>
				3261	</tr>
				3262
				3263	<tr>
				3264	<td><a name="tag-type">@type</a></td>
				3265	<td>
				3266	<code>
				3267	@type Type<br/>
				3268	@type {Type}
				3269	</code>
				3270	<p><i>For example:</i></p>
				3271	<CODE_SNIPPET>
				3272	/**
				3273	* The message hex ID.
				3274	* @type {string}
				3275	*/
				3276	var hexId = hexId;
				3277	</CODE_SNIPPET>
				3278	</td>
				3279	<td>
				3280	Identifies the <a href="#JsTypes">type</a> of a variable,
				3281	property, or expression. Curly braces are not required around
				3282	most types, but some projects mandate them for all types, for
				3283	consistency.
				3284	</td>
				3285	</tr>
				3286
				3287	<tr>
				3288	<td><a name="tag-typedef">@typedef</a></td>
				3289	<td>
				3290	<code>@typedef</code>
				3291	<p><i>For example:</i></p>
				3292	<CODE_SNIPPET>
				3293	/** @typedef {(string\|number)} */
				3294	goog.NumberLike;
				3295
				3296	/** @param {goog.NumberLike} x A number or a string. */
				3297	goog.readNumber = function(x) {
				3298	...
				3299	}
				3300	</CODE_SNIPPET>
				3301	</td>
				3302	<td>
				3303	This annotation can be used to declare an alias of a more
				3304	<a href="#Typedefs">complex type</a>.
				3305	</td>
				3306	</tr>
				3307
				3308
				3309
				3310	</tbody>
				3311	</table>
				3312
				3313
				3314
				3315	<p>
				3316	You may also see other types of JSDoc annotations in third-party
				3317	code. These annotations appear in the
				3318	<a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagReference">
				3319	JSDoc Toolkit Tag Reference
				3320	</a>
				3321	but are currently discouraged in Google code. You should consider
				3322	them "reserved" names for future use. These include:
				3323	<ul>
				3324	<li>@augments</li>
				3325	<li>@argument</li>
				3326	<li>@borrows</li>
				3327	<li>@class</li>
				3328	<li>@constant</li>
				3329	<li>@constructs</li>
				3330	<li>@default</li>
				3331	<li>@event</li>
				3332	<li>@example</li>
				3333	<li>@field</li>
				3334	<li>@function</li>
				3335	<li>@ignore</li>
				3336	<li>@inner</li>
				3337	<li>@link</li>
				3338	<li>@memberOf</li>
				3339	<li>@name</li>
				3340	<li>@namespace</li>
				3341	<li>@property</li>
				3342	<li>@public</li>
				3343	<li>@requires</li>
				3344	<li>@returns</li>
				3345	<li>@since</li>
				3346	<li>@static</li>
				3347	<li>@version</li>
				3348	</ul>
				3349	</p>
				3350	</SUBSECTION>
				3351	</BODY>
				3352	</STYLEPOINT>
				3353
				3354	<STYLEPOINT title="Providing Dependencies With goog.provide">
				3355	<SUMMARY>
				3356	Only provide top-level symbols.
				3357	</SUMMARY>
				3358	<BODY>
				3359	<p>
				3360	All members defined on a class should be in the same file. So, only
				3361	top-level classes should be provided in a file that contains multiple
				3362	members defined on the same class (e.g. enums, inner classes, etc).
				3363	</p>
				3364	<p>Do this:</p>
				3365	<CODE_SNIPPET>
				3366	goog.provide('namespace.MyClass');
				3367	</CODE_SNIPPET>
				3368	<p>Not this:</p>
				3369	<BAD_CODE_SNIPPET>
				3370	goog.provide('namespace.MyClass');
				3371	goog.provide('namespace.MyClass.Enum');
				3372	goog.provide('namespace.MyClass.InnerClass');
				3373	goog.provide('namespace.MyClass.TypeDef');
				3374	goog.provide('namespace.MyClass.CONSTANT');
				3375	goog.provide('namespace.MyClass.staticMethod');
				3376	</BAD_CODE_SNIPPET>
				3377	<p>
				3378	Members on namespaces may also be provided:
				3379	</p>
				3380	<CODE_SNIPPET>
				3381	goog.provide('foo.bar');
				3382	goog.provide('foo.bar.method');
				3383	goog.provide('foo.bar.CONSTANT');
				3384	</CODE_SNIPPET>
				3385	</BODY>
				3386	</STYLEPOINT>
				3387
				3388	<STYLEPOINT title="Compiling">
				3389	<SUMMARY>Required</SUMMARY>
				3390	<BODY>
				3391
				3392
				3393	<p>Use of JS compilers such as the
				3394	<a href="https://code.google.com/closure/compiler/">Closure Compiler</a>
				3395	is required for all customer-facing code.</p>
				3396
				3397
				3398
				3399
				3400	</BODY>
				3401	</STYLEPOINT>
				3402
				3403	<STYLEPOINT title="Tips and Tricks">
				3404	<SUMMARY>JavaScript tidbits</SUMMARY>
				3405	<BODY>
				3406	<SUBSECTION title="True and False Boolean Expressions">
				3407	<p>The following are all false in boolean expressions:</p>
				3408	<ul>
				3409	<li><code>null</code></li>
				3410	<li><code>undefined</code></li>
				3411	<li><code>''</code> the empty string</li>
				3412	<li><code>0</code> the number</li>
				3413	</ul>
				3414	<p>But be careful, because these are all true:</p>
				3415	<ul>
				3416	<li><code>'0'</code> the string</li>
				3417	<li><code>[]</code> the empty array</li>
				3418	<li><code>{}</code> the empty object</li>
				3419	</ul>
				3420
				3421	<p>This means that instead of this:</p>
				3422	<BAD_CODE_SNIPPET>
				3423	while (x != null) {
				3424	</BAD_CODE_SNIPPET>
				3425	<p>you can write this shorter code (as long as you don't expect x to
				3426	be 0, or the empty string, or false):</p>
				3427	<CODE_SNIPPET>
				3428	while (x) {
				3429	</CODE_SNIPPET>
				3430
				3431	<p>And if you want to check a string to see if it is null or empty,
				3432	you could do this:</p>
				3433	<BAD_CODE_SNIPPET>
				3434	if (y != null && y != '') {
				3435	</BAD_CODE_SNIPPET>
				3436	<p>But this is shorter and nicer:</p>
				3437	<CODE_SNIPPET>
				3438	if (y) {
				3439	</CODE_SNIPPET>
				3440
				3441	<p><strong>Caution:</strong> There are many unintuitive things about
				3442	boolean expressions. Here are some of them:</p>
				3443	<ul>
				3444	<li><code>
				3445	Boolean('0') == true<br/>
				3446	'0' != true</code></li>
				3447	<li><code>
				3448	0 != null<br/>
				3449	0 == []<br/>
				3450	0 == false</code></li>
				3451	<li><code>
				3452	Boolean(null) == false<br/>
				3453	null != true<br/>
				3454	null != false</code></li>
				3455	<li><code>
				3456	Boolean(undefined) == false<br/>
				3457	undefined != true<br/>
				3458	undefined != false</code></li>
				3459	<li><code>
				3460	Boolean([]) == true<br/>
				3461	[] != true<br/>
				3462	[] == false</code></li>
				3463	<li><code>
				3464	Boolean({}) == true<br/>
				3465	{} != true<br/>
				3466	{} != false</code></li>
				3467	</ul>
				3468	</SUBSECTION>
				3469
				3470	<SUBSECTION title="Conditional (Ternary) Operator (?:)">
				3471	<p>Instead of this:</p>
				3472	<CODE_SNIPPET>
				3473	if (val) {
				3474	return foo();
				3475	} else {
				3476	return bar();
				3477	}
				3478	</CODE_SNIPPET>
				3479	<p>you can write this:</p>
				3480	<CODE_SNIPPET>
				3481	return val ? foo() : bar();
				3482	</CODE_SNIPPET>
				3483
				3484	<p>The ternary conditional is also useful when generating HTML:</p>
				3485	<CODE_SNIPPET>
				3486	var html = '<input type="checkbox"' +
				3487	(isChecked ? ' checked' : '') +
				3488	(isEnabled ? '' : ' disabled') +
				3489	' name="foo">';
				3490	</CODE_SNIPPET>
				3491	</SUBSECTION>
				3492
				3493	<SUBSECTION title="&& and \|\|">
				3494	<p>These binary boolean operators are short-circuited, and evaluate
				3495	to the last evaluated term.</p>
				3496
				3497	<p>"\|\|" has been called the 'default' operator, because instead of
				3498	writing this:</p>
				3499	<BAD_CODE_SNIPPET>
				3500	/** @param {=} opt_win /
				3501	function foo(opt_win) {
				3502	var win;
				3503	if (opt_win) {
				3504	win = opt_win;
				3505	} else {
				3506	win = window;
				3507	}
				3508	// ...
				3509	}
				3510	</BAD_CODE_SNIPPET>
				3511	<p>you can write this:</p>
				3512	<CODE_SNIPPET>
				3513	/** @param {=} opt_win /
				3514	function foo(opt_win) {
				3515	var win = opt_win \|\| window;
				3516	// ...
				3517	}
				3518	</CODE_SNIPPET>
				3519
				3520	<p>"&&" is also useful for shortening code. For instance,
				3521	instead of this:</p>
				3522	<BAD_CODE_SNIPPET>
				3523	if (node) {
				3524	if (node.kids) {
				3525	if (node.kids[index]) {
				3526	foo(node.kids[index]);
				3527	}
				3528	}
				3529	}
				3530	</BAD_CODE_SNIPPET>
				3531
				3532	<p>you could do this:</p>
				3533	<CODE_SNIPPET>
				3534	if (node && node.kids && node.kids[index]) {
				3535	foo(node.kids[index]);
				3536	}
				3537	</CODE_SNIPPET>
				3538
				3539	<p>or this:</p>
				3540	<CODE_SNIPPET>
				3541	var kid = node && node.kids && node.kids[index];
				3542	if (kid) {
				3543	foo(kid);
				3544	}
				3545	</CODE_SNIPPET>
				3546
				3547	<p>However, this is going a little too far:</p>
				3548	<BAD_CODE_SNIPPET>
				3549	node && node.kids && node.kids[index] && foo(node.kids[index]);
				3550	</BAD_CODE_SNIPPET>
				3551	</SUBSECTION>
				3552
				3553	<SUBSECTION title="Iterating over Node Lists">
				3554	<p>Node lists are often implemented as node iterators with a filter.
				3555	This means that getting a property like length is O(n), and
				3556	iterating over the list by re-checking the length will be
				3557	O(n^2).</p>
				3558	<BAD_CODE_SNIPPET>
				3559	var paragraphs = document.getElementsByTagName('p');
				3560	for (var i = 0; i < paragraphs.length; i++) {
				3561	doSomething(paragraphs[i]);
				3562	}
				3563	</BAD_CODE_SNIPPET>
				3564
				3565	<p>It is better to do this instead:</p>
				3566	<CODE_SNIPPET>
				3567	var paragraphs = document.getElementsByTagName('p');
				3568	for (var i = 0, paragraph; paragraph = paragraphs[i]; i++) {
				3569	doSomething(paragraph);
				3570	}
				3571	</CODE_SNIPPET>
				3572
				3573	<p>This works well for all collections and arrays as long as the array
				3574	does not contain things that are treated as boolean false.</p>
				3575
				3576	<p>In cases where you are iterating over the childNodes you can also
				3577	use the firstChild and nextSibling properties.</p>
				3578	<CODE_SNIPPET>
				3579	var parentNode = document.getElementById('foo');
				3580	for (var child = parentNode.firstChild; child; child = child.nextSibling) {
				3581	doSomething(child);
				3582	}
				3583	</CODE_SNIPPET>
				3584	</SUBSECTION>
				3585	</BODY>
				3586	</STYLEPOINT>
				3587	</CATEGORY>
				3588
				3589
				3590
				3591	<PARTING_WORDS>
				3592	<p>
				3593	<em>BE CONSISTENT</em>.
				3594	</p>
				3595
				3596	<p>
				3597	If you're editing code, take a few minutes to look at the code
				3598	around you and determine its style. If they use spaces around
				3599	all their arithmetic operators, you should too. If their
				3600	comments have little boxes of hash marks around them, make your
				3601	comments have little boxes of hash marks around them too.
				3602	</p>
				3603
				3604	<p>
				3605	The point of having style guidelines is to have a common vocabulary
				3606	of coding so people can concentrate on what you're saying rather
				3607	than on how you're saying it. We present global style rules here so
				3608	people know the vocabulary, but local style is also important. If
				3609	code you add to a file looks drastically different from the existing
				3610	code around it, it throws readers out of their rhythm when they go to
				3611	read it. Avoid this.
				3612	</p>
				3613
				3614	</PARTING_WORDS>
				3615
				3616	<p align="right">
				3617	Revision 2.93
				3618	</p>
				3619
				3620
				3621	<address>
				3622	Aaron Whyte<br/>
				3623	Bob Jervis<br/>
				3624	Dan Pupius<br/>
				3625	Erik Arvidsson<br/>
				3626	Fritz Schneider<br/>
				3627	Robby Walker<br/>
				3628	</address>
robbyw@google.com	bb32401	2010-07-12 22:02:20 +0000	[diff] [blame]	3629	</GUIDE>