javascript_coding_standards.diviner
536b0867dea7stable

javascript_coding_standards.diviner
View Options

			@title Javascript Coding Standards
			@group contrib

			This document describes Javascript coding standards for Phabricator and Javelin.

			= Overview =

			This document outlines technical and style guidelines which are followed in
			Phabricator and Javelin. Contributors should also follow these guidelines. Many
			of these guidelines are automatically enforced by lint.

			These guidelines are essentially identical to the Facebook guidelines, since I
			basically copy-pasted them. If you are already familiar with the Facebook
			guidelines, you can probably get away with skimming this document.


			= 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 ##if## and ##for##.
			- Put a space after commas in argument lists.
			- Put space around operators like ##=##, ##<##, 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; follow those
			rules.

			- Name variables using ##lowercase_with_underscores##.
			- Name classes using ##UpperCamelCase##.
			- Name methods and properties using ##lowerCamelCase##.
			- Name global functions using ##lowerCamelCase##. Avoid defining global
			functions.
			- Name constants using ##UPPERCASE##.
			- Write ##true##, ##false##, and ##null## in lowercase.
			- "Internal" methods and properties should be prefixed with an underscore.
			For more information about what "internal" means, see
			Leading Underscores, below.

			= Comments =

			- Strongly prefer ##//## 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 ##[]## and ##{}##, not ##new Array## and ##new Object##.
			- When creating an object literal, do not quote keys unless required.

			= Examples =

			if/else:

			lang=js
			if (x > 3) {
			// ...
			} else if (x === null) {
			// ...
			} else {
			// ...
			}

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

			for (iteration):

			lang=js
			for (var ii = 0; ii < 10; ii++) {
			// ...
			}

			Prefer ii, jj, kk, etc., as iterators, since they're easier to pick out
			visually and react better to "Find Next..." in editors.

			for (enumeration):

			lang=js
			for (var k in obj) {
			// ...
			}

			Make sure you use enumeration only on Objects, not on Arrays. For more details,
			see @{article:Javascript Object and Array}.

			switch:

			lang=js
			switch (x) {
			case 1:
			// ...
			break;
			case 2:
			if (flag) {
			break;
			}
			break;
			default:
			// ...
			break;
			}

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

			If you insist on having a "fall through" case that does not end with ##break##,
			make it clear in a comment that you wrote this intentionally. For instance:

			lang=js
			switch (x) {
			case 1:
			// ...
			// Fall through...
			case 2:
			//...
			break;
			}

			= Leading Underscores =

			By convention, methods names which start with a leading underscore are
			considered "internal", which (roughly) means "private". The critical difference
			is that this is treated as a signal to Javascript processing scripts that a
			symbol is safe to rename since it is not referenced outside the current file.

			The upshot here is:

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

			If you treat them as though they were "private", you won't run into problems.

phab/src/docs/user/contributing/javascript_coding_standards.diviner536b0867dea7stable

javascript_coding_standards.divinerView Options

phab/src/docs/user/contributing/javascript_coding_standards.diviner
536b0867dea7stable

javascript_coding_standards.diviner
View Options