1. The Art of Readable Code
Simple and Practical Techniques for Writing Better Code

3. Code Should Be Easy to
Understand

4. for (Node* node = list->head;
node != NULL;
node = node->next) {
Print(node->data);
}
Node* node = list->head;
if (node == NULL) return;
while (node->next != NULL) {
Print(node->data);
node = node->next;
}
if (node != NULL) {
Print(node->data);
}

5. (_=[_=[]][(_+!![])[$=(!!_/!!_)]+(!!$+_)[-~-~$]+'v'+(!
(_/_)+[])[-~-~$]+(!([]/($))+[])[$]+([]+!_)[-~-~$]+(!!
{}+[])[-~-~$]])()[(!({}+_)+_)[$]+(!({}+[])+[])[-~$]+
((''+!![]+''))[-~-~$]+(!![]+'')[$]+((!!_+[]))[$-$]]($/
$);
alert(1)

6. Key Idea
• Code should be easy to understand.
• Minimize the time it would take for
someone else to understand it.

7. Is Smaller Always Better?

8. Conflict with Other Goals?
Easy to Test
Well-Architected
Code Efficient
Highly Maintainable
…

9. Three Levels
• Surface Level
• Loops & Logic
• Reorganizing

10. Surface-Level

11. Packing Information into
Names

12. • Specific
• Avoid Generic Names
• Prefer Concrete Names
• Extra Information
• Length vs Meaning
• Formatting

14. Word
Alternative
send
deliver, dispatch, announce, distribute, route
find
search, extract, locate, recover
start
launch, create, begin, open
make
create, set up, build, generate, compose, add, new

16. Naming Conventions
• Noun for variable name, object name, class
name, property name, arguments name
• Verb for function name, method name

18. Case
maptypeCtrl.streetMapMgr(true);
A Better One
maptypeCtrl.showStreetMap();

20. Length
• Shorter names for shorter scopes
• Longer names for larger scopes

21. Names That Can’t Be
Misconstrued

22. Key Idea
• Asking yourself, “What other meanings
could someone interpret from this name?”

23. • Prefer min and max for(inclusive) limits
• Naming booleans
• Matching expectations of Users

24. Case
var read_password = true;
A Better One
var need_password = true;
var user_authenticated = true;

25. Case
map.getBestMap(points);
A Better One
map.setViewport(points);

26. Aesthetic

27. Aesthetic
• Use consistent layout.
• Make similar code look similar.
• Group related lines of code into blocks.

30. Knowing What to
Comment

31. Key Idea
• The purpose of commenting is to help the
reader know as much as the writer did.

32. What NOT to Comment
• KEY IDEA：Don’t comment on the facts
that can be derived quickly from the code
itself

34. Case
!
// 延时关闭信息窗⼝口
setTimeout(function(){
map.closeInfoWindow();
}, 100);

35. Case
!
// 添加为全局对象；
window.mapSubway = me;

36. Recording Your Thoughts
• Include “Director Commentary”
• Comment the Flaws in Your Code
• Comment on Your Constants

37. Put Yourself in the
Reader’s Shoes
• Anticipating Likely Questions
• Advertising Likely Pitfalls
• “Big Picture”
• Summary

39. Precise & Compact
Comments

40. • Keep Comments Compact
• Describe Function Behavior Precisely
• Use Examples
• State the Intent

41. Case
// 返回⽂文件⾏行数
int CountLines(string filename) {...}
A Better One
// 计算换⾏行符'n'的个数
int CountLines(string filename) {...}

42. Case
if (mode ==
var a =
b =
minutes
"bustime") {
minutes % 10,
parseInt(minutes / 10);
= a != 0 ?
(a > 5 ?
(++b * 10) : b ?
(b * 10) : 5):
minutes;
Need Examples!

43. Loops & Logic

44. Making Control Flow
Easy to Read

45. KEY IDEA
• Make your logic as “natural” as possible

46. Case
if (length >= 10)
if (10 <= length)
while (bytes_received < bytes_expected)
while (bytes_expected > bytes_received)

47. Order of if/else Blocks
• Positive First
• Simpler First
• Interesting First

48. ?: Conditional Expression
• Often Less Readable

49. KEY IDEA
• Minimize the time needed for someone to
understand it instead of minimizing the
number of lines.

50. ADVICE
• Use ternary ?: only for the simplest cases.

51. • Avoid do/while Loops
• Returning Early form a Function
• Minimize Nesting
• Flow of Execution

53. Breaking Down Giant
Expressions

54. • Explaining Variables
• Summary Variables
• Use De Morgan’s Laws
• Break Down Giant Statements

55. Case
if (line.split(':')[0] == 'admin')
var userName = line.split(':')[0];
if (userName == 'admin')

56. Case
if (navigator.userAgent.indexOf('UC') > -1)
if (navigator.userAgent.indexOf('UC') == -1)
var isUC =
navigator.userAgent.indexOf('UC') > -1;
if (isUC)
if (!isUC)

57. Case
var update_highlight = function (message_num) {
if ($("#vote_value" + message_num).html() === "Up") {
$("#thumbs_up" + message_num).addClass("highlighted");
$("#thumbs_down" + message_num).removeClass("highlighted");
} else if ($("#vote_value" + message_num).html() === "Down") {
$("#thumbs_up" + message_num).removeClass("highlighted");
$("#thumbs_down" + message_num).addClass("highlighted");
} else {
$("#thumbs_up" + message_num).removeClass("highighted");
$("#thumbs_down" + message_num).removeClass("highlighted");
}
};

58. var update_highlight = function (message_num) {
var thumbs_up = $("#thumbs_up" + message_num);
var thumbs_down = $("#thumbs_down" + message_num);
var vote_value = $("#vote_value" + message_num).html();
var hi = "highlighted";
if (vote_value === "Up") {
thumbs_up.addClass(hi);
thumbs_down.removeClass(hi);
} else if (vote_value === "Down") {
thumbs_up.removeClass(hi);
thumbs_down.addClass(hi);
} else {
thumbs_up.removeClass(hi);
thumbs_down.removeClass(hi);
}
};

59. Variables

60. Problems
• More variables, harder to keep track of them
• Bigger variable’s scope, longer you have to keep
track of them
• More often variable changes, harder to keep
track of its current value

61. Eliminating Variables
• Useless Temporary Variables
• Eliminating Intermediate Results
• Eliminating Control Flow Variables

63. Case
var remove_one = function(array, value_to_remove) {
var index_to_remove = null;
for (var i = 0; i < array.length; i ++) {
if (array[i] === value_to_remove) {
index_to_remove = i;
break;
}
}
if (index_to_remove !== null) {
array.slice(index_to_remove, 1);
}
}

64. Case
var remove_one = function(array, value_to_remove) {
for (var i = 0; i < array.length; i ++) {
if (array[i] === value_to_remove) {
array.slice(i, 1);
return;
}
}
}

65. Shrink the Scope
• Make variable visible by as few lines of code
as possible.

66. Prefer write-once
variables
• KEY IDEA: The more places a variable is
manipulated, the harder it is to reason
about its current value.

67. Reorganizing

68. Extracting Unrelated
Subproblems

69. Case
function findClosestLocation(latLng, latLngs) {
var closest;
var closest_dist = Number.MAX_VALUE;
for each latlng in latLngs, calculate the
distance, if new distance is shorter than
current, set closest to the new latlng
return closest;
}

70. What is the unrelated
subproblem?
Compute the
spherical distance

71. • Pure Utility Code
• General-Purpose Code
• Project-Specific Functionality
• Simplifying an Existing Interface

72. Case
Cookie
setCookie(key, value);
getCookie(key);
deleteCookie(key);
hasCookie(key);

73. Further Reading

74. One Task at a Time

75. KEY IDEA
• Code should be organized so that it’s doing
only one task at a time.

76. Turning Thoughts into Code

77. • Describe what code needs to do, in plain
English(we should use Chinese)
• Pay attention to key words and phrases
• Write your code to match description

78. Case
$is_admin = is_admin_request();
if ($document) {
if (!$is_admin
&& ($document['username']) != $_SESSION['username'])){
return not_authorized();
}
} else {
if (!$is_admin) {
return not_authorized();
}
}
// continue rendering the page ...

79. Case
if (is_admin_request()) {
// authorized
} elseif ($document
&& $document['username']) !=
$_SESSION['username'])) {
// authorized
} else {
return not_authorized();
}
// continue rendering the page ...

80. Writing Less Code

81. KEY IDEA
• The most readable code is
NO CODE AT ALL

83. Case
• Calculating Distance Between Two
Locations

84. • Don’t implement code that you won’t need
• Simplify requirements
• Keep your codebase small
• Be familiar with Libraries around you

86. Further Reading

87. Further Reading

88. Further Reading

89. Q&A