Differential D21624 Diff 51472 src/docs/contributor/general_coding_standards.diviner

Changeset View

Standalone View

src/docs/contributor/general_coding_standards.diviner

	@title General Coding Standards			@title General Coding Standards
	@group standards			@group standards

	This document is a general coding standard for contributing to Phabricator,			This document is a general coding standard for contributing to Phabricator,
	Arcanist, libphutil and Diviner.			Arcanist, and Diviner.

	= Overview =			= Overview =

	This document contains practices and guidelines which apply across languages.			This document contains practices and guidelines which apply across languages.
	Contributors should follow these guidelines. These guidelines are not			Contributors should follow these guidelines. These guidelines are not
	hard-and-fast but should be followed unless there is a compelling reason to			hard-and-fast but should be followed unless there is a compelling reason to
	deviate from them.			deviate from them.

	▲ Show 20 Lines • Show All 117 Lines • ▼ Show 20 Lines
	handling and makes it easier to get right than wrong:			handling and makes it easier to get right than wrong:

	execx('echo %s > file.bak', $data); // Good			execx('echo %s > file.bak', $data); // Good
	do_something_dangerous();			do_something_dangerous();

	Filesystem::writeFile('file.bak', $data); // Best			Filesystem::writeFile('file.bak', $data); // Best
	do_something_dangerous();			do_something_dangerous();

	See @{article@libphutil:Command Execution} for details on the APIs used in this			See @{article@arcanist:Command Execution} for details on the APIs used in this
	example.			example.

	= Documentation, Comments and Formatting =			= Documentation, Comments and Formatting =

	- Prefer to remove code by deleting it over removing it by commenting it out.			- Prefer to remove code by deleting it over removing it by commenting it out.
	It shall live forever in source control, and can be retrieved therefrom if			It shall live forever in source control, and can be retrieved therefrom if
	it is ever again called upon.			it is ever again called upon.
	- In source code, use only ASCII printable characters plus space and linefeed.			- In source code, use only ASCII printable characters plus space and linefeed.
	Do not use UTF-8 or other multibyte encodings.			Do not use UTF-8 or other multibyte encodings.