Language-Independent Guidelines
Some guidelines simply have near-universal applicability. This where you’ll find them.
all-ind
Indent your code correctly.
- Reason
- This is a direct corollary to fnd-mng. Should be self-explanatory, and if it isn’t, talk to a professor or TA!
- Protip
- Language-savvy code editors can take care of indentation automatically, when properly configured. Try to take advantage of this to minimize busy work.
all-spc
Indent with spaces, not tabs.
- Reason
- Spaces are presented way more consistently than tabs are, and thus code indented with spaces will look more consistent than code indented with tabs, whether the code is in a browser, a terminal window, or an editor.
- Exceptions
- Languages where tabs have a specific meaning, such as in Makefiles.
- Protip
- Most code editors worth their salt can automate this for you. Figure out how you can get your editor to do this.
all-max
Maintain a maximum line length.
- Reason
-
As with
all-spc
, the reason is again consistency. Some editors or code displays will auto-linebreak; others won’t. A suitable maximum line length is one that, most of the time, represents a typical horizontal display size. That way, even if auto-linebreak might happen, at this width it most likely won’t. - Current Recommendation
-
For current screen sizes,
120
fixed-width characters works well.
all-cmt
Use comments only when the code itself is not sufficiently clear.
- Corollary
- If you’re using comments a lot, then your code probably should get clearer.
- Reason
- Comments clutter your code and multiply the amount of maintenance involved when your code evolves.
- Clarification
- Note that this guideline does not say “Never use comments.” As “Uncle Bob” Martin wrote in the dicussion thread of Apologies in Code, “I will write comments; but when I do I consider it to be a failure of expression. Sometimes the fault is our languages. Sometimes the fault is our own talent or imagination.”
- Further Reading
all-names
Choose descriptive names.
- Corollary
- Don’t be afraid of long names. Long but clear names pay for themselves in ease of understanding and maintenance.
- Another Corollary
-
Names with an ordinal like
customer1
orproduct2
are almost never the right ones. - Reason
-
Good names go a looooooong way toward making your code self-explanatory (so this supports
all-cmt
as well). - Exceptions
- Languages with severe name limitations—in which case, you may want to consider using a different one!
all-dry
Don’t repeat yourself (DRY).
- Explanation
- If distinct blocks of code do the same thing (or almost the same thing, differing only in terms of certain values), then that probably should be a single block of code. Consolidate them into a function. If the code is not identical, extract the differences as parameters.
- Reason
- Repetitive code is harder to maintain. If you fix a bug in one copy, you will need to fix that same bug in all of the other copies. Sometimes repeating this fix is forgotten.
all-cont
Maintain at least one indent for line/statement continuations.
- Details
- When breaking a line or statement and continuing it in successive lines (perhaps because you were following all-max, but possibly for other reasons as well), indent the successive lines at least once. Depending on the language, additional indentation such as a standard double-indent or by aligning continued lines with delimiters (e.g., parentheses, braces) may be recommended or desirable.
- Corollary
- Break a statement at a point where it is clearly incomplete, such as at an operator, separator, or an opening (line-breakable) delimiter. This reinforces the signal that the statement is not yet finished.
- Reason
- One or more indents will show that the line itself does not stand on its own, being a continuation of the line above it. This appropriately reflects the structure of the code.
- Current Recommendation
- When no additional specifics exist, a double-indent works well. This shows that the line is a continuation and also distinguishes it from standard nesting.
all-newline
Use blank lines liberally to separate distinct, cohesive sections of code.
- Reason
- Negative space is as useful in code presentation as it is in visual design—it provides a non-intrusive but effective way to separate distinct regions of code. Blank lines are useful in separating functions from each other, separating variable declarations from each other, etc. It is another technique for allowing code’s appearance to reflect its structure.
all-bool
Don’t compare conditions to Boolean values—they already are!
- Reason
- Conditions are themselves Boolean (or Boolean-equivalent) in most programming languages, so it is redundant to compare these to Boolean values.
- Python
-
Don’t
if (value in list) == True: process_value(value)
Do
if value in list: process_value(value)
- JavaScript
-
Don’t
if (inputElement.enabled === false) { panel.style.backgroundColor = "gray"; }
Do
if (!inputElement.enabled) { panel.style.backgroundColor = "gray"; }
all-ifassgn
if
statements whose only action is the assignment or returning of a value should be replaced with a conditional expression.
- Reason
-
In the spirit of “make your code communicate its intent,” an
if
statement is meant to choose among possible actions that a program can make. When said “action” is restricted only to the assignment of a variable or returning a function result, then what your code is really trying to do is choose among possible values, not actions. In this situation, a conditional expression (to the degree that the language provides it) conveys the point more clearly and is less prone to error.
- Python
-
Don’t
if authorized(user): return STATUS_OK else: return STATUS_FORBIDDEN
Do
return STATUS_OK if authorized(user) else STATUS_FORBIDDEN
- JavaScript
-
Don’t
var color = options.color; if (!color) { color = DEFAULT_COLOR; }
Do
var color = options.color || DEFAULT_COLOR;
all-parenexpr
Do not include spaces inside parenthetical/nested expressions.
- Reason
-
Nearly all languages allow nested expressions, and nearly all of these use parentheses to delimit their
subexpressions. As delimiters, the parentheses are more appropriately thought of as part of the inner
expression, so adding spaces after and before the left and right parentheses, respectively, does not accurately
reflect the structure of the code
fnd-mng
.
- Examples
-
return (-b + sqrt((b * b) - (4 * a * c))) / (2 * a);
if (i > max || j < (min * 4) + skip) {
- Anti-Examples
-
return ( -b + sqrt( ( b * b ) - ( 4 * a * c ) ) ) / ( 2 * a );
if ( i > max || j < ( min * 4 ) + skip ) {
- On Precedence
- Note that even if one argues for taking advantage of operator precedence to minimize parentheticals, in the general case (a) this will not always be possible to rely on precedence, (b) some precedence rules are confusing anyway (e.g., conditional expression precedence in JavaScript) and (c) it is generally safer not to aggressively rely on precedence anyway in case a precedence rule is easily misunderstood (ditto conditional expressions in JavaScript) or code might be read by personnel who do not have the same knowledge level of the language.