No OneTemporary
Actions

Size

9 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/contributor/javascript_coding_standards.diviner b/src/docs/contributor/javascript_coding_standards.diviner
	index 7bff8a3bdf..65e15e6b55 100644
	--- a/src/docs/contributor/javascript_coding_standards.diviner
	+++ b/src/docs/contributor/javascript_coding_standards.diviner
	@@ -1,140 +1,139 @@
	@title Javascript Coding Standards
	@group standards

	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.
	diff --git a/src/docs/contributor/php_coding_standards.diviner b/src/docs/contributor/php_coding_standards.diviner
	index a180a2ff3a..d79d340326 100644
	--- a/src/docs/contributor/php_coding_standards.diviner
	+++ b/src/docs/contributor/php_coding_standards.diviner
	@@ -1,170 +1,169 @@
	@title PHP Coding Standards
	@group standards

	This document describes PHP coding standards for Phabricator and related
	projects (like Arcanist and libphutil).

	= Overview =

	This document outlines technical and style guidelines which are followed in
	libphutil. 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 probably don't need to read this super thoroughly.


	= Spaces, Linebreaks and Indentation =

	- Use two spaces for indentation. Don't use tab literal 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 a 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 =

	- Name variables and functions using ##lowercase_with_underscores##.
	- Name classes using ##UpperCamelCase##.
	- Name methods and properties using ##lowerCamelCase##.
	- Use uppercase for common acronyms like ID and HTML.
	- Name constants using ##UPPERCASE##.
	- Write ##true##, ##false## and ##null## in lowercase.

	= Comments =

	- Do not use "#" (shell-style) comments.
	- Prefer "//" comments inside function and method bodies.

	= PHP Language Style =

	- Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
	- Prefer casts like ##(string)## to casting functions like ##strval()##.
	- Prefer type checks like ##$v === null## to type functions like
	##is_null()##.
	- Avoid all crazy alternate forms of language constructs like "endwhile"
	and "<>".
	- Always put braces around conditional and loop blocks.

	= PHP Language Features =

	- Use PHP as a programming language, not a templating language.
	- Avoid globals.
	- Avoid extract().
	- Avoid eval().
	- Avoid variable variables.
	- Prefer classes over functions.
	- Prefer class constants over defines.
	- Avoid naked class properties; instead, define accessors.
	- Use exceptions for error conditions.
	- Use type hints, use `assert_instances_of()` for arrays holding objects.

	= Examples =

	if/else:

	if ($some_variable > 3) {
	// ...
	} else if ($some_variable === null) {
	// ...
	} else {
	// ...
	}

	You should always put braces around the body of an if clause, even if it is only
	one line long. Note spaces around operators and after control statements. Do not
	use the "endif" construct, and write "else if" as two words.

	for:

	for ($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.

	foreach:

	foreach ($map as $key => $value) {
	// ...
	}

	switch:

	switch ($value) {
	case 1:
	// ...
	break;
	case 2:
	if ($flag) {
	// ...
	break;
	}
	break;
	default:
	// ...
	break;
	}

	`break` statements should be indented to block level.

	array literals:

	$junk = array(
	'nuts',
	'bolts',
	'refuse',
	);

	Use a trailing comma and put the closing parenthesis on a separate line so that
	diffs which add elements to the array affect only one line.

	operators:

	$a + $b; // Put spaces around operators.
	$omg.$lol; // Exception: no spaces around string concatenation.
	$arr[] = $element; // Couple [] with the array when appending.
	$obj = new Thing(); // Always use parens.

	function/method calls:

	// One line
	eject($cargo);

	// Multiline
	AbstractFireFactoryFactoryEngine::promulgateConflagrationInstance(
	$fuel,
	$ignition_source);

	function/method definitions:

	function example_function($base_value, $additional_value) {
	return $base_value + $additional_value;
	}

	class C {
	public static function promulgateConflagrationInstance(
	IFuel $fuel,
	IgnitionSource $source) {
	// ...
	}
	}

	class:

	class Dog extends Animal {

	const CIRCLES_REQUIRED_TO_LIE_DOWN = 3;

	private $favoriteFood = 'dirt';

	public function getFavoriteFood() {
	return $this->favoriteFood;
	}
	}

File Metadata

Mime Type: text/x-diff
Expires: Thu, Nov 6, 6:58 AM (6 h, 17 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 321722
Default Alt Text: (9 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions