The Art of Readable Code

Theory in Practice

By Dustin Boswell



Originally published

Nov 29, 2011




Jun 20, 2018


Jun 21, 2018

PurchaseExternal link
Variable/parameter naming
Highly important for readability
Tradeoff between and
Larger scope → be more specific, carry more information because it can be used in more places with less context
Small scope → the context is there to understand what the variable does
Consider more than just yourself: consider your future self and others who might work on the code
Capitalize class and constructor names (used with the new operator), camelCase function names
Pick concrete, direct names (ex. select rather than filter). Approach naming conventions as a devil’s advocate; ask “how can this be misinterpreted?”.
Good names can prevent off-by-1 errors and outputs opposite of your expectation
Avoid negatives and double-negatives when possible, especially with boolean variables
Keep to conventions and expectations
For example, get methods are assumed to be O(1)
Calculations should instead be labeled by the action being done: countSum() is likely a better name than getSum() if it requires iterating over a whole array
This prevents misuse by downstream components
Commenting and spacing
Minimizes comments which provide the same information in different places by centralizing your docs and writing modular methods
Consistent aligning, columns, and spacing makes it easier to stop typos and bugs
When defining multiple variables at once, use order to convey meaning
…order in which you use them
…order of importance
…order alphabetically
“Don’t comment on facts that can be derived quickly from the code itself.”
Don’t write comments to compensate for poorly named variables/functions--fix them
Comment all issues, problems, questions in your code
Be a and avoid the : when writing code you have put much thought into design and development though an outside reader did not go through the same process
defensive programmer
illusion of transparency
Touch on edge cases, implementation decisions/meanings to clarify
Can serve as a “ comments must align with code objectives
Avoid pronouns, explain unintuitive function parameters
Loops and conditionals
Choosing sides for if (a < b)
LHS: being interrogated, value more in flux (for example, expected)
RHS: being compared against, value more constant (for example, actual)
This is most similar to English (“If I’m over 18…”)
Instead of minimizing the number of lines, a better metric is to minimize the time needed for someone to understand it.
Put conditions up front —> avoid do…while loops and similar logic flows
Minimize nesting
Return as early as possible to simplify logic / dependencies
In loops, leverage continue and break keywords
Prefer break statements in while loops to having a Boolean variable which eventually resolves to false. This simplifies logic, especially if the variable is used in multiple places.
for loops in general are difficult to read, keep to functional alternatives when possible
Well-named intermediate variables can go a long way to improve code readability. Space to write should not take precedence over time to understand.
Sometimes solving the opposite problem yields far simpler, more readable logic.
DRY: save variables that you calculate more than once. This improve readability and may serve to improve performance.
Modularize classes and have as many static functions as possible. Shrink variable scopes to ensure readability, minimize complexity, and maximize data security.
Leverage closures in JS to avoid unwanted globals.
Use variables as soon after you define them as possible—all of the variables in the current scope should be relevant. Anything else should be phased out of the scope.
Strategy: describe the problem in English, glean keywords from your description, and leverage those to implement your solution.
Extract unrelated subproblems even if they’re only called once. Functions extract away distracting operations like calculations and string concatenation, leaving more readable and direct code.

← Back to all books