Book Notes: The Art of Readable Code by Dustin Boswell

I highlight and take notes when I read nonfiction books. Once I finish a book, I format and edit my notes so that I can easily remind myself of what I learned without having to reread the book. These notes are not a substitute for reading the book, they only serve as a reminder of key concepts.

The fewer lines a variable is in scope, the shorter its name is allowed to be. Variables used in larger scopes must be less ambiguous so they are allowed to have longer names.

Don’t use project specific abbreviations — someone new to the project won’t know what they mean. “So our rule of thumb is: would a new teammate understand what the name means? If so, then it’s probably okay.”

“The clearest way to name a limit is to put max_ or min_ in front of the thing being limited.”

“In general, adding words like is, has, can, or should can make booleans more clear.”

“The best names are ones that can’t be misconstrued — the person reading your code will understand it the way you meant it, and no other way.”

“Everyone prefers to read code that’s aesthetically pleasing. By “formatting” your code in a consistent, meaningful way, you make it easier and faster to read.”

“The purpose of commenting is to help the reader know as much as the writer did.”

More comments aren’t necessarily better — the comments take up valuable screen real estate, so if there is a comment in the code “it better be worth it”.

“Don’t Comment Bad Names — Fix the Names Instead”

“Instead of minimizing the number of lines, a better metric is to minimize the time needed for someone to understand it.”

“The simplest way to break down an expression is to introduce an extra variable that captures a smaller subexpression. This extra variable is sometimes called an “explaining variable” because it helps explain what the subexpression means.”

“One technique [to clean up code] is to see if you can solve the problem the “opposite” way. Depending on the situation you’re in, this could mean iterating through arrays in reverse or filling in some data structure backward rather than forward.”

In general, keep scopes short and finish tasks as quickly as possible.

“The more places a variable is manipulated, the harder it is to reason about its current value.”

“The advice for this chapter is to aggressively identify and extract unrelated subproblems. Here’s what we mean: Look at a given function or block of code, and ask yourself, “What is the high-level goal of this code?” For each line of code, ask, “Is it working directly to that goal? Or is it solving an unrelated subproblem needed to meet it?” If enough lines are solving an unrelated subproblem, extract that code into a separate function.”

“Code that does multiple things at once is harder to understand. A single block of code might be initializing new objects, cleansing data, parsing inputs, and applying business logic, all at the same time.”

Break code up into small, easy to understand fragments. This makes understanding easier and reduces potential for bugs.

“do only one task at a time.”

“When explaining a complex idea to someone, it’s easy to confuse them with all the little details. It’s a valuable skill to be able to explain an idea “in plain English,” so that someone less knowledgeable than you can understand. It requires distilling an idea down to the most important concepts. Doing this not only helps the other person understand but also helps you think about your own ideas more clearly.”

“This chapter discussed the simple technique of describing your program in plain English and using that description to help you write more natural code. This technique is deceptively simple, but very powerful.”

“Knowing when not to code is possibly the most important skill a programmer can learn. Every line of code you write is a line that has to be tested and maintained. By reusing libraries or eliminating features, you can save time and keep your codebase lean and mean.”

“When you start a project, it’s natural to get excited and think of all the cool features you’ll want to implement. But programmers tend to overestimate how many features are truly essential to their project. A lot of features go unfinished or unused or just complicate the application.”