Homec4science
Diffusion libphutil (production) Browse

libphutil/src/docs/drafts/general_style.txt
bc1c139c818bproduction

Last Change
Raw File

general_style.txt
View Options

This document is a general style guide for writing code at Facebook. For language specific references, see [[Articles/PHP Style Reference]], [[Articles/Javascript Style Reference]], and [http://www.intern.facebook.com/intern/wiki/index.php/CppStyle C++ Style Reference].
= Overview =
In contrast to the language-specific style references which mandate rules, this document contains recommended practices and guidelines which apply across languages. These guidelines are not hard-and-fast, but should be followed unless there is a compelling reason to deviate from them.
= Code Complexity =
* Prefer to write simple code which is easy to understand. The simplest code is not necessarily the smallest, and some changes which make code larger (such as decomposing complex expressions and choosing more descriptive names) may also make it simpler. Be willing to make size tradeoffs in favor of simplicity.
* Prefer simple methods and functions, which take a small number of parameters. Avoid methods and functions which are extremely long and complex, or take an innumerable host of parameters. When possible, decompose monolithic, complex methods into several focused, simpler ones.
* Prefer widely adopted idioms that simplify common operations, like idx() in PHP.
* Avoid putting many ideas on a single line of code (e.g., don't branch, assign, negate, bitflip, transform, and do some whacky side effects that depend on short circuiting in a single expression).
For example, avoid this kind of code:
<code> COUNTEREXAMPLE
$category_map = array_combine(
$dates,
array_map(create_function('$z', 'return date("F Y", $z);'), $dates));
</code>Expressing this complex transformation more simply produces more readable code:
<code> $category_map = array();
foreach ($dates as $date) {
$category_map[$date] = date('F Y', $date);
}
</code>Another example:
<code> COUNTEREXAMPLE
return array_map1(
'array_rekey',
array_select($assocs, array('id2', 'time')),
array('id2' => 'interviewee', 'time' => 'start_time'));
</code>This is simpler as:
<code> $result = array();
foreach ($assocs as $assoc) {
$result[$assoc['id2']] = array(
'interviewee' => $assoc['id2'],
'start_time' => $assoc['time'],
);
}
return $result;
</code>And, obviously, don't do this sort of thing:
<code> COUNTEREXAMPLE
if ($val = $some->complicatedConstruct() && !!~blarg_blarg_blarg() & $flags
? HOPE_YOU_MEMORIZED == $all_the_lexical_binding_powers : <<<'Q'
${hahaha}
Q
);
</code>
= Performance =
* Prefer to write efficient code.
* Strongly prefer to drive optimization decisions with hard data. Avoid optimizing based on intuition or rumor if you can not support it with concrete measurements.
* Prefer to optimize code that is slow and runs often. Optimizing code that is fast and runs rarely is usually a waste of time, especially if it makes that code more difficult to understand or maintain. You can determine if code is fast or slow by measuring it.
* Prefer to discard outright any information anyone gives you about the performance characteristics of anything if it isn't backed up with concrete data. They are the villainous servants of dark, shadowy creatures that feed on deception and chaos. These demons have no desire but to tempt you into making ``optimizations'' that produce code which is slower and more difficult to maintain without actual performance benefits.
We have a good set of tools that often make it easy to obtain concrete data about optimization decisions, like [http://www.intern.facebook.com/intern/phprof/ PHProf] (PHP), [http://www.intern.facebook.com/intern/microbench/ Microbench] (PHP), and [http://www.intern.facebook.com/intern/wiki/index.php/FBUnit#Benchmarks C++ Benchmarking with FBUnit].
= Naming Things =
* Follow language-specific conventions.
* Name things unambiguously.
* Choose descriptive names.
* Avoid nonstandard abbreviations (common abbreviations like ID, URI and HTTP are fine).
* Spell things correctly.
* Use correct grammar.
For example, avoid these sorts of naming choices:
<code> COUNTEREXAMPLE
$PIE->GET_FLAVOR(); // Unconventional.
$thing->doStuff(); // Ambiguous.
$list->empty(); // Ambiguous.
$e = 3; // Not descriptive.
$this->updtHndlr(); // Nonstandard abbreviation.
$this->chackSpells(); // Misspelling, ungrammatical.
</code>Prefer these:
<code> $pie->getFlavor(); // Conventional.
$pie->bake(); // Unambiguous.
$list->isEmpty(); // Unambiguous.
$list->makeEmpty(); // Unambiguous.
$edge_count = 3; // Descriptive.
$this->updateHandler(); // No nonstandard abbreviations.
$this->getID(); // Standard abbreviation.
$this->checkSpelling(); // Correct spelling and grammar.
</code>
= Error Handling =
* Prefer to fail fast and loudly. The maximum cost of script termination is known, bounded, and fairly small. The maximum cost of continuing script execution when errors have occurred is unknown and unbounded. It also makes your APIs much easier to use and debug. A good way to fail loudly is often to throw an exception.
When you ignore errors, defer error handling, or degrade the severity of errors by treating them as warnings and then dismissing them, you risk dangerous behavior which may be difficult to troubleshoot:
<code> COUNTEREXAMPLE
exec('echo '.$data.' > file.bak'); // Bad!
do_something_dangerous();
exec('echo '.$data.' > file.bak', $out, $err); // Also bad!
if ($err) {
debug_rlog("Unable to copy file!");
}
do_something_dangerous();
</code>Instead, fail loudly:
<code> exec('echo '.$data.' > file.bak', $out, $err); // Better
if ($err) {
throw new Exception("Unable to copy file!");
}
do_something_dangerous();
</code>Better is to use or write an API which simplifies condition handling:
<code> execx('echo %s > file.bak', $data); // Good
do_something_dangerous();
Filesystem::writeFile('file.bak', $data); // Best
do_something_dangerous();
</code>See [[Articles/System Commands]] for details on the APIs used in this example.
= Documentation, Comments and Formatting=
* Prefer to document code. See [[Articles/Writing Diviner Documentation]] and [[Articles/Writing Good Documentation]] for explanations and examples. Writing good documentation is difficult and time consuming, but often pays for itself.
* 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 is again called upon.
* In source code, use only ASCII printable characters plus space and linefeed. Do not use UTF-8 or other multibyte encodings.
c4science · Help