javascript_style.txt
28575b0de3d5stable

javascript_style.txt
View Options


			This document is a quick reference guide for Javascript style at Facebook. All Javascript code (except third-party code) should follow these conventions.

			= Spaces, Linebreaks and Indentation =

			* Use two spaces for indentation. Don't use literal tab characters.
			* Use Unix linebreaks (`\n'), not MSDOS (`\r\n') or OS9 (`\r').
			* Use K&R style braces and spacing.
			* Put a space after control keywords like <tt>if</tt> and <tt>for</tt>.
			* Put a space after commas in argument lists.
			* Put space around operators like <tt>=</tt>, <tt><</tt>, etc.
			* Don't put spaces after function names.
			* Parentheses should hug their contents.
			* Generally, prefer to wrap code at 80 columns.

			= Case and Capitalization =

			The Javascript language unambiguously dictates casing/naming rules, and we follow those rules.

			* Name variables using <tt>lowercase_with_underscores</tt>.
			* Name classes and bundles using <tt>UpperCamelCase</tt>.
			* Name methods and properties using <tt>lowerCamelCase</tt>. <b>Exception</b>: event handlers in the form ``onwhatever'' should be lowercase with no spaces.
			* Name global functions using <tt>lowerCamelCase</tt>. Avoid defining global functions whenever possible.
			* Name constants using <tt>UPPERCASE</tt>.
			* Write <tt>true</tt>, <tt>false</tt>, and <tt>null</tt> in lowercase.
			* ``Internal'' methods and properties should be prefixed with an underscore. For more information about what ``internal'' means, see <b>Leading Underscores</b>, below.

			= Comments =

			* Strongly prefer <tt>//</tt> comments for making comments inside the bodies of functions and methods (this lets someone easily comment out a block of code while debugging later).

			= Javascript Language =

			* Use <tt>[]</tt> and <tt>{}</tt>, not <tt>new Array</tt> and <tt>new Object</tt>.
			* When creating an object literal, do not quote keys.

			= Examples =

			<b>if/else:</b>

			<code> if (x > 3) {
			// ...
			} else if (x === null) {
			// ...
			} else {
			// ...
			}

			</code>You should always put braces around the body of an if clause, even if it is only one line. Note that operators like <tt>></tt> and <tt>===</tt> are also surrounded by spaces.

			<b>for (iteration):</b>

			<code> for (var i = 0; i < 10; i++) {
			// ...
			}

			</code>If you want to be really fancy, you can use <tt>ii</tt>, <tt>jj</tt>, <tt>kk</tt>, etc., instead of <tt>i</tt>, <tt>j</tt>, and <tt>k</tt>. They stand out a little better and react more properly to "Find Next..." in editors, since they are uncommon and won't usually show up in the middle of words. Iteration should be used on Arrays only, not Objects. For more details, see [[Articles/Object and Array]].

			<b>for (enumeration):</b>

			<code> for (var k in obj) {
			// ...
			}

			</code>Make sure you use enumeration only on Objects, not on Arrays. For more details, see [[Articles/Object and Array]].

			<b>switch:</b>

			<code> switch (x) {
			case 1:
			// ...
			break;
			case 2:
			if (flag) {
			break;
			}
			break;
			default:
			// ...
			break;
			}

			</code><tt>break</tt> statements should be indented to block level. If you don't push them in, you end up with an inconsistent rule for conditional <tt>break</tt> statements, as in the <tt>2</tt> case.

			If you insist on having a "fall through" case that does not end with <tt>break</tt>, make it clear in a comment that you wrote this intentionally, lest someone come by and correct your "mistake." For instance:

			<code> switch (x) {
			case 1:
			// ...
			// FALL THROUGH
			case 2:
			//...
			</code>

			= Classes =

			Much more detail on how to build classes is available in [[Articles/Object-Oriented Javascript]].

			<code> function /* class */ Animal(name) {
			this.name = name;
			}

			copy_properties(Animal.prototype, {
			getName : function() {
			return name;
			}
			});

			</code>
			= Haste Headers =

			All Javascript files should have Haste headers declaring their dependencies. More information is available in [[Articles/Haste Introduction]] and [[Articles/Using Haste]].

			<code> /**
			* Brief description of the file.
			*
			* @requires vector dom async
			* @provides animal-component
			* @author epriestley
			*/

			</code>
			= Leading Underscores =

			By convention, methods names which start with a leading underscore are considered ``internal'', which (roughly) means ``private''. The significant distinction here is that, at some point in the future, we'll build a scope-aware minification tool that renames identifiers which aren't referenced outside of a file's scope.

			The upshot here is:

			<code> - name internal methods which shouldn't be called outside of a file's scope
			with a leading underscore; and
			- <b>never</b> call an internal method from another file.

			</code>If you treat them as though they were ``private'', you won't run into problems.

			= Documentation =

			Documentation should be done with Javadoc docblocks. You can read more about writing Javascript documentation in [[Articles/Writing Diviner Documentation]].

			<code> /**
			* Check if there are remaining pancakes in the stack. This function detects
			* any pancake, even stale or soggy pancakes.
			*
			* @param Plate Which plate to check.
			* @return bool If true, there are pancakes in the stack.
			*
			* @author epriestley
			*/
			areThereMorePancakes : function(plate) {
			// ...
			}</code>

libphutil/src/docs/drafts/javascript_style.txt28575b0de3d5stable

javascript_style.txtView Options

libphutil/src/docs/drafts/javascript_style.txt
28575b0de3d5stable

javascript_style.txt
View Options