Three Changes You Should Always Make Before Checking In Any Code

Photo by Maico Amorim

This story originally appeared in Hacker Noon on March 11, 2017.

A code refactor always leaves me with a feeling of accomplishment. Although major refactorings are the most satisfying, every project doesn’t always warrant them. Here are 3 quick and easy refactorings that I make to all of my projects in order to improve code readability:

1. Clean up formatting

The overall format of your code is what makes it possible to quickly navigate to areas of interest. Consistent indentation, line breaks, and patterns help programmers skim large chunks of code. Take the following sloppily formatted code for example:

and compare it to this:

The second example above consistently indents lines, adds new lines, and follows consistent coding patterns. This makes it easy to skim the code quickly.

Books have chapters, headings, and paragraphs defined by formatting that make it easy to find what is needed at a glance — formatting code makes it possible to find things easily too.

2. Rename classes, methods, and variables

Classes, methods, and variables should be named in such that they help the programmer understand what is happening in the code. The shorter the scope of an object the more permissible it is to use shorter names (eg. “i” as a counter in a loop that’s only a line or two long).

It’s easy to use uninformative names when writing a “first draft” of your program, but using the first name that comes to mind isn’t always the best choice. Take a look at the following example:

versus:

Using names that make sense make it much easier for someone else (or your future-self) to figure out what your code is doing.

3. Break up long expressions

When you get into a code writing groove it’s easy to keep chaining commands together or using single-line syntax to speed up your writing. Often times, I look back on my code a day later and I see long expressions similar to this. Take a look at this two line expression:

Compared against this expression that has been broken out across multiple lines:

Although the first code snippet is technically shorter and has fewer lines, it is nearly unreadable. The second snippet breaks out the the if logic and breaks up all of the chained methods into more logical variables. The result? Code logic that is much easier to follow.

 

Thanks for reading. You might also enjoy following me on Twitter.

Want to learn even more SQL?

Sign up for my newsletter to receive weekly SQL tips!

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.”

Thanks for reading. You might also enjoy following me on Twitter.

Want to learn even more SQL?

Sign up for my newsletter to receive weekly SQL tips!