The Art of Readable Code

The Art of
Readable Code

pedro@morais.it
@pedromorais
morais on app.net

Dustin Boswell
Trevor Foucher

O’Reilly
Nov 2011

code should be easy
to understand

1. Pack information
into your names

be speciﬁc

X GetPage
✓ DownloadPage

avoid generic names

X tmp
X retval

var euclidean_norm = function (v) {
var retval = 0.0;
for (var i = 0; i < v.length; i += 1)
retval += v[i] * v[i];
X
return Math.sqrt(retval);
};

var euclidean_norm = function (v) {
var sum_squares = 0.0;
for (var i = 0; i < v.length; i += 1)
sum_squares += v[i] * v[i];
return Math.sqrt(sum_squares);
✓
};

attach details

X duration
✓ duration_ms

X password
✓ plaintext_password

careful with
abbreviations

X BEManager

✓ str
✓ eval

X
.ﬁlter(“year <= 2000”)

CART_TOO_BIG_LIMIT = 10
STOP = 10 X
CART_MAX_ITEMS = 10
LAST = 10 ✓

read_password = True
X
✓
needs_to_read_password
password_has_been_read

# Import the user's email contacts,
# and match them to users in our system.
# Then display a list of those users that
X
# he/she isn't already friends with.
def suggest_new_friends(user, email_password):
friends = user.friends()
friend_emails = set(f.email for f in friends)
contacts = import_contacts(user.email, email_password)
contact_emails = set(c.email for c in contacts)
non_friend_emails = contact_emails - friend_emails
suggested_friends = User.objects.select(email__in=non_friend_emails)
display['user'] = user
display['friends'] = friends
display['suggested_friends'] = suggested_friends
return render("suggested_friends.html", display)

def suggest_new_friends(user, email_password):
# Get the user's friends' email addresses.
✓
friends = user.friends()
friend_emails = set(f.email for f in friends)

# Import all email addresses from this user's email account.
contacts = import_contacts(user.email, email_password)
contact_emails = set(c.email for c in contacts)

# Find matching users that they aren't already friends with.
non_friend_emails = contact_emails - friend_emails
suggested_friends = User.objects.select(email__in=non_friend_emails)

# Display these lists on the page.
display['user'] = user
display['friends'] = friends
display['suggested_friends'] = suggested_friends

return render("suggested_friends.html", display)

// The class definition of Account

X
class Account {
! public:
! ! // Constructor
! ! Account();
! ! // Set the profit member
! ! void SetProfit(double profit);
! ! // Returns the profit
! ! double GetProfit();
};

✓
# remove everything after the second '*'
name = '*'.join(line.split('*')[:2])

ﬁx bad names,
don’t explain them

X
// Enforce limits on the Reply as stated in the Request,
// such as the number of items returned, or total byte
// size, etc.
void CleanReply(Request request, Reply reply);

X
// Make sure 'reply' meets the count/byte/etc.
// limits from the 'request'
void EnforceRequestLimits(Request request, Reply reply);

include “director’s
commentary”
// Surprisingly, a binary tree was 40% faster
// than a hash table for this data.
// The cost of computing a hash was more
// than the left/right comparisons.

// This heuristic might miss a few words.
// That's OK; solving this 100% is hard.

comment code ﬂaws

TODO
FIXME
HACK
XXX

4. Make your control
ﬂow easy to follow

write expressions like
you’d say it
if (length > 10)
while (bytes_received < bytes_expected)
✓
X
if (10 <= length)
while (bytes_expected > bytes_received)

if/else ordering

if (a == b) { if (a != b) {
// Case One ... // Case Two ...
} else { } else {
// Case Two ... // Case One ...
} }

deal with positive ﬁrst

✓
if (debug) {
// Case One ...
} else {
// Case Two ...
}

deal with simpler ﬁrst
if (!file) {

✓
// Log an error
} else {
// Actually do stuff
// ...
// ...
// ...
}

deal with interesting ﬁrst
if (url.HasQueryParameter("expand_all"))) {

✓
// Interesting code
// ...
// ...
// ...
} else {
// “Easy” case
}

return early

public boolean Contains(String str, String substr) {
if (str == null || substr == null) return false;
if (substr.equals("")) return true;

✓
...
}

minimize nesting
if (user_result == SUCCESS) {
if (permission_result != SUCCESS) {
reply.WriteErrors("error reading permissions");
reply.Done();
return;
}
reply.WriteErrors("");
} else {
reply.WriteErrors(user_result);

X
}
reply.Done();

5. Break down giant
expressions

explain with vars

if line.split(':')[0].strip() == "root":
... X
✓
username = line.split(':')[0].strip()
if username == "root":
...

summarize with vars

if (request.user.id == document.owner_id) {
// user can edit this document...
if (request.user.id != document.owner_id) { // document is read-only...
}

}
...
if (request.user.id != document.owner_id) {
// document is read-only...
}

X

summarize with vars
final boolean user_owns_document =
(request.user.id == document.owner_id);

if (user_owns_document) {
// user can edit this document...
}

✓
...
if (!user_owns_document) {
// document is read-only...
}

use De Morgan’s laws
if (!(file_exists && !is_protected))
Error("Sorry, could not read file.");
X
✓
if (!file_exists || is_protected)
Error("Sorry, could not read file.");

X
many variables
broad scope
changing frequently

remove unnecessary vars
now = datetime.datetime.now()
root_message.last_view_time = now
X
root_message.last_view_time = datetime.datetime.now()

✓

make your variable
visible by as few lines
of code as possible

prefer write-once
variables

7. Extract unrelated
subproblems

factor out
lines that are working
towards a subproblem

separate the
generic code from the
project- speciﬁc code

create a lot of
general-purpose code

8. Do one thing at a
time

1.
ﬁgure out what tasks
your code is doing

2.
separate those tasks into
functions or sections

X
void UpdateCounts(HttpDownload hd) {
// Figure out the Exit State, if available.
if (!hd.has_event_log() || !hd.event_log().has_exit_state()) {
counts["Exit State"]["unknown"]++;
} else {
string state_str = ExitStateTypeName(hd.event_log().exit_state());
counts["Exit State"][state_str]++;
}

// If there are no HTTP headers at all, use "unknown" for the remaining elements.
if (!hd.has_http_headers()) {
counts["Http Response"]["unknown"]++;
counts["Content-Type"]["unknown"]++;
return;
}

HttpHeaders headers = hd.http_headers();

// Log the HTTP response, if known, otherwise log "unknown"
if (!headers.has_response_code()) {
counts["Http Response"]["unknown"]++;
} else {
string code = StringPrintf("%d", headers.response_code());
counts["Http Response"][code]++;
}

// Log the Content-Type if known, otherwise log "unknown"
if (!headers.has_content_type()) {
counts["Content-Type"]["unknown"]++;
} else {
string content_type = ContentTypeMime(headers.content_type());
counts["Content-Type"][content_type]++;
}
}

void UpdateCounts(HttpDownload hd) {
// Task: define default values for each of the values we want to extract
string exit_state = "unknown";
string http_response = "unknown";
string content_type = "unknown";

// Task: try to extract each value from HttpDownload, one by one
if (hd.has_event_log() && hd.event_log().has_exit_state()) {
exit_state = ExitStateTypeName(hd.event_log().exit_state());
}
if (hd.has_http_headers() && hd.http_headers().has_response_code()) {
http_response = StringPrintf("%d", hd.http_headers().response_code());
}
if (hd.has_http_headers() && hd.http_headers().has_content_type()) {
content_type = ContentTypeMime(hd.http_headers().content_type());
}

✓
// Task: update counts[]
counts["Exit State"][exit_state]++;
counts["Http Response"][http_response]++;
counts["Content-Type"][content_type]++;
}

be familiar with
your libraries

10. Break the rules
when you have a
good reason to do it

Thanks!

pedro@morais.it
@pedromorais
morais on app.net

The Art of Readable Code

Recommended

Recommended

More Related Content

Featured

Featured (20)

The Art of Readable Code

Editor's Notes