recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title General Coding Standards
2@group standards
3
4This document is a general coding standard for contributing to Phorge,
5Arcanist, and Diviner.
6
7= Overview =
8
9This document contains practices and guidelines which apply across languages.
10Contributors should follow these guidelines. These guidelines are not
11hard-and-fast but should be followed unless there is a compelling reason to
12deviate from them.
13
14= Code Complexity =
15
16 - Prefer to write simple code which is easy to understand. The simplest code
17 is not necessarily the smallest, and some changes which make code larger
18 (such as decomposing complex expressions and choosing more descriptive
19 names) may also make it simpler. Be willing to make size tradeoffs in favor
20 of simplicity.
21 - Prefer simple methods and functions which take a small number of parameters.
22 Avoid methods and functions which are long and complex, or take an
23 innumerable host of parameters. When possible, decompose monolithic, complex
24 methods into several focused, simpler ones.
25 - Avoid putting many ideas on a single line of code.
26
27For example, avoid this kind of code:
28
29 COUNTEREXAMPLE
30 $category_map = array_combine(
31 $dates,
32 array_map(create_function('$z', 'return date("F Y", $z);'), $dates));
33
34Expressing this complex transformation more simply produces more readable code:
35
36 $category_map = array();
37 foreach ($dates as $date) {
38 $category_map[$date] = date('F Y', $date);
39 }
40
41And, obviously, don't do this sort of thing:
42
43 COUNTEREXAMPLE
44 if ($val = $some->complicatedConstruct() && !!~blarg_blarg_blarg() & $flags
45 ? HOPE_YOU_MEMORIZED == $all_the_lexical_binding_powers : <<<'Q'
46 ${hahaha}
47 Q
48 );
49
50
51= Performance =
52
53 - Prefer to write efficient code.
54 - Strongly prefer to drive optimization decisions with hard data. Avoid
55 optimizing based on intuition or rumor if you can not support it with
56 concrete measurements.
57 - Prefer to optimize code which is slow and runs often. Optimizing code which
58 is fast and runs rarely is usually a waste of time, and can even be harmful
59 if it makes that code more difficult to understand or maintain. You can
60 determine if code is fast or slow by measuring it.
61 - Reject performance discussions that aren't rooted in concrete data.
62
63In Phorge, you can usually use the builtin XHProf profiling to quickly
64gather concrete performance data.
65
66
67= Naming Things =
68
69 - Follow language-specific conventions.
70 - Name things unambiguously.
71 - Choose descriptive names.
72 - Avoid nonstandard abbreviations (common abbreviations like ID, URI and HTTP
73 are fine).
74 - Spell words correctly.
75 - Use correct grammar.
76
77For example, avoid these sorts of naming choices:
78
79 COUNTEREXAMPLE
80 $PIE->GET_FLAVOR(); // Unconventional.
81 $thing->doStuff(); // Ambiguous.
82 $list->empty(); // Ambiguous -- is it isEmpty() or makeEmpty()?
83 $e = 3; // Not descriptive.
84 $this->updtHndlr(); // Nonstandard abbreviation.
85 $this->chackSpulls(); // Misspelling, ungrammatical.
86
87Prefer these:
88
89 $pie->getFlavor(); // Conventional.
90 $pie->bake(); // Unambiguous.
91 $list->isEmpty(); // Unambiguous.
92 $list->makeEmpty(); // Unambiguous.
93 $edge_count = 3; // Descriptive.
94 $this->updateHandler(); // No nonstandard abbreviations.
95 $this->getID(); // Standard abbreviation.
96 $this->checkSpelling(); // Correct spelling and grammar.
97
98
99= Error Handling =
100
101 - Strongly prefer to detect errors.
102 - Strongly prefer to fail fast and loudly. The maximum cost of script
103 termination is known, bounded, and fairly small. The maximum cost of
104 continuing script execution when errors have occurred is unknown and
105 unbounded. This also makes APIs much easier to use and problems far easier
106 to debug.
107
108When you ignore errors, defer error handling, or degrade the severity of errors
109by treating them as warnings and then dismissing them, you risk dangerous
110behavior which may be difficult to troubleshoot:
111
112 COUNTEREXAMPLE
113 exec('echo '.$data.' > file.bak'); // Bad!
114 do_something_dangerous();
115
116 exec('echo '.$data.' > file.bak', $out, $err); // Also bad!
117 if ($err) {
118 debug_rlog("Unable to copy file!");
119 }
120 do_something_dangerous();
121
122Instead, fail loudly:
123
124 exec('echo '.$data.' > file.bak', $out, $err); // Better
125 if ($err) {
126 throw new Exception("Unable to copy file!");
127 }
128 do_something_dangerous();
129
130But the best approach is to use or write an API which simplifies condition
131handling and makes it easier to get right than wrong:
132
133 execx('echo %s > file.bak', $data); // Good
134 do_something_dangerous();
135
136 Filesystem::writeFile('file.bak', $data); // Best
137 do_something_dangerous();
138
139See @{article@arcanist:Command Execution} for details on the APIs used in this
140example.
141
142= Documentation, Comments and Formatting =
143
144 - Prefer to remove code by deleting it over removing it by commenting it out.
145 It shall live forever in source control, and can be retrieved there from if
146 it is ever again called upon.
147 - In source code, use only ASCII printable characters plus space and linefeed.
148 Do not use UTF-8 or other multibyte encodings.