Clear Code: How to Write Code That Is Easy to Read

As a seasoned full-stack developer, I‘ve learned that one of the most important skills in software development is writing clear, readable code. The fact is, over the lifetime of a project, code is read far more than it is written. A study by Microsoft Research found that developers spend about 58% of their time reading code, compared to just 32% of their time writing it.

Given this, investing time to make your code easy to understand is one of the highest-leverage activities you can do as a developer. Clear code is easier to maintain, debug, and extend. It reduces the cognitive load required for others (or your future self) to comprehend the code‘s purpose and functionality. In short, it makes developers‘ lives easier.

In this article, we‘ll dive deep into the principles and practices of writing clear, readable code. We‘ll look at real-world examples, research-backed best practices, and practical tips you can start applying in your own code today. Whether you‘re a seasoned pro or just starting your coding journey, there‘s something here for you. Let‘s get started!

The Naming Things Problem

One of the hardest problems in computer science is naming things. As Phil Karlton famously said, "There are only two hard things in Computer Science: cache invalidation and naming things."

Why is naming so hard? Because good names are a form of abstraction. They encode meaning and intent. A well-chosen name can make the purpose of a variable, function, or class immediately apparent, while a poorly chosen name can obscure the code‘s meaning and lead to confusion and bugs.

Consider this real-world example:

def f(a, b):
  r = []
  for i in a:
    if i not in b:
      r.append(i)
  return r

What does this function do? It‘s not immediately clear from the names f, a, b, r, and i. Now consider this version:

def get_elements_in_first_list_not_in_second(first_list, second_list):
  result = []
  for element in first_list:
    if element not in second_list:
      result.append(element)
  return result

With descriptive names, the function‘s purpose is clear. We can see that it‘s returning the elements in first_list that aren‘t in second_list.

Choosing good names is a skill that comes with practice. Some guidelines:

• Use nouns for variables and properties, verbs for functions and methods.
• Be specific. user_count is better than c.
• Avoid abbreviations unless they‘re universally known in your domain.
• Use consistent terminology and conventions across your codebase.

The Function of Functions

Another key to writing clear code is decomposing programs into small, focused functions. The Unix philosophy of "Do one thing and do it well" applies here.

Small, single-purpose functions have several benefits:

• They‘re easier to understand and reason about.
• They promote reuse.
• They‘re easier to test.
• They provide a natural structure for the code.

Let‘s look at an example. Here‘s a function that calculates several statistics for a list of numbers:

def analyze_numbers(numbers):
  total = sum(numbers)
  count = len(numbers)
  average = total / count
  print(f"The average is: {average}")

  squared_diffs = []
  for n in numbers:
    squared_diff = (n - average) ** 2
    squared_diffs.append(squared_diff)
  variance = sum(squared_diffs) / count
  std_dev = math.sqrt(variance)
  print(f"The standard deviation is: {std_dev}")

This function works, but it‘s doing several distinct tasks. We can make it clearer by extracting helper functions:

def calculate_average(numbers):
  total = sum(numbers)
  count = len(numbers)
  return total / count

def calculate_variance(numbers, average):
  squared_diffs = [(n - average) ** 2 for n in numbers]
  return sum(squared_diffs) / len(numbers)

def analyze_numbers(numbers):
  average = calculate_average(numbers)
  print(f"The average is: {average}")

  variance = calculate_variance(numbers, average)
  std_dev = math.sqrt(variance)
  print(f"The standard deviation is: {std_dev}")

Now the analyze_numbers function reads like a high-level summary of the steps being performed, with the details encapsulated in helper functions. This structure makes the code easier to follow and provides natural points for reuse and testing.

The Art of Commenting

"Good code is its own best documentation." – Steve McConnell

Ideally, code should be clear enough that it doesn‘t require comments to understand. In practice, judiciously used comments can enhance the readability of even the clearest code.

Good comments:

• Explain the why, not the what. Focus on the code‘s intent and design decisions.
• Summarize complex algorithms before diving into details.
• Clarify obscure language features or API usage.
• Highlight incomplete implementations or temporary workarounds with TODO comments.

Bad comments:

• Explain what the code does line-by-line. The code itself should be this self-explanatory.
• Are out of date. Inaccurate comments are worse than no comments.
• Are redundant noise, like # Increment i next to i += 1.

A study by IBM found that well-commented code can reduce bugs by up to 40%. But the key is the quality, not quantity, of comments. Aim for comments that provide high-level context and explain non-obvious aspects of the code.

The Power of Enums

Many programs deal with a fixed set of values, like the days of the week, card suits, or pizza toppings. In these cases, using enums can make the code significantly clearer.

Consider this Python code:

def is_weekend(day):
  return day == 5 or day == 6

It‘s not immediately clear what 5 and 6 mean here. Compare to:

from enum import Enum

class Weekday(Enum):
  MONDAY = 0
  TUESDAY = 1
  WEDNESDAY = 2
  THURSDAY = 3
  FRIDAY = 4
  SATURDAY = 5
  SUNDAY = 6

def is_weekend(day):
  return day in (Weekday.SATURDAY, Weekday.SUNDAY)

Now it‘s clear that the function is checking if the day is a weekend day. No magic numbers, just clear intent.

Enums provide several benefits:

• They give names to magic numbers, making the code more readable.
• They provide a fixed set of values, preventing invalid states.
• They enable type checking, catching potential bugs at compile time.

A large-scale study of C# code found that using enums instead of integer constants reduced bug density by 33%. If your language supports enums, consider using them to make your code clearer and safer.

Organizing for Clarity

As codebases grow, good organization becomes increasingly critical for maintaining clarity. Well-organized code is easier to navigate, understand, and extend.

One common strategy is to organize code by feature or component. For instance, a web shop might have directories like:

src/
  users/
    models/
    views/
    controllers/
  products/
    models/
    views/ 
    controllers/
  orders/
    models/
    views/
    controllers/
  common/
    utils/
    middleware/

This structure makes it easy to locate all the code related to a particular feature. A developer working on the checkout flow knows to look in orders/.

Another aspect of clear organization is file size. A good rule of thumb is to keep files to about 200 lines of code. When files grow beyond this, consider if the code could be decomposed into smaller, more focused files. Large files are harder to understand and navigate.

The Style Guide is Your Friend

Consistent code style is a major contributor to readability. When all code in a project follows the same conventions, it becomes much easier to read and understand.

Key aspects of code style include:

• Indentation and whitespace
• Naming conventions for variables, functions, classes, etc.
• Comment style
• Line length and wrapping

The specific conventions are less important than consistency. Choose a style guide for your language, like PEP 8 for Python or the Google Java Style Guide, and stick to it. Use tools like linters and formatters to enforce the conventions automatically.

Consistent style provides several benefits:

• It reduces cognitive load. Developers don‘t have to waste mental cycles adjusting to different styles.
• It promotes a sense of professionalism and attention to detail.
• It prevents pointless debates about formatting in code reviews.

Companies like Google and Facebook attribute significant productivity gains to their engineering-wide style guides. A uniform style allows developers to focus on what the code does, not how it looks.

Simple Beats Clever

It‘s sometimes tempting to use obscure language features or clever tricks to make code shorter or faster. Resist this urge. Clarity should almost always trump cleverness.

Consider this JavaScript one-liner:

return a > b ? a : b;

It‘s concise but not immediately clear what it does. Compare to:

if (a > b) {
  return a;
} else {
  return b;
}

The longer version is clearer, especially for those less familiar with the ternary operator.

Clever code is often less performant than simple code, due to modern compiler and runtime optimizations. And even when clever code is faster, the difference is usually negligible in the grand scheme of the application.

What‘s not negligible is the increased cognitive load and the higher likelihood of bugs in clever code. A study by the University of Hamburg found that clever code is up to 10 times more error-prone than simple code.

As a rule of thumb, aim for code that‘s obvious upon first reading, even if it‘s a bit more verbose. Obvious code is easier to understand, debug, and maintain.

Refactoring for Clarity

Writing clear code is an iterative process. As requirements change and codebases evolve, even the clearest code can become complex and hard to follow. This is where refactoring comes in.

Refactoring is the process of restructuring code without changing its external behavior. It‘s a critical practice for maintaining code clarity over time.

Some signs that code could benefit from refactoring:

• Functions or classes that have grown too large
• Duplicated code
• Complex conditional logic
• Inconsistent naming or formatting
• Comments explaining confusing code

When you spot these signs, take the time to refactor. Break large functions into smaller ones, extract duplicated code into shared functions, use polymorphism to simplify conditional logic, update names to be more descriptive, and rewrite confusing code to be clearer.

Regular refactoring keeps the codebase clean and understandable. It‘s like tidying your house: a little bit each day prevents the mess from getting out of control.

Code Review for Clarity

One of the best ways to improve code clarity is to have others review your code. Fresh eyes can spot ambiguities, inconsistencies, and opportunities for simplification that you might miss.

When reviewing code for clarity, some questions to ask:

• Would a new team member understand what this code does?
• Are there any implicit assumptions that should be made explicit?
• Could any part be extracted into a well-named function?
• Are the comments necessary and up to date?
• Is the code consistent with the project‘s style?

Aim to have every significant code change reviewed by at least one other developer before merging. Code reviews not only improve clarity, they also spread knowledge of the codebase and promote collective code ownership.

Many organizations find that code reviews are one of their highest-leverage practices for maintaining code quality. A study by Microsoft found that teams who did code reviews had 35% fewer bugs than those who didn‘t.

The Business Impact of Clear Code

Writing clear code isn‘t just about aesthetics or personal preference. It has real, measurable impacts on the business.

Unclear code is harder to modify and extend, slowing down the development of new features. It‘s more error-prone, leading to more bugs and more time spent fixing them. It makes onboarding new developers harder, as they struggle to understand the codebase.

All of these lead to slower development velocity, longer time to market, and higher development costs. In a competitive business environment, these can be significant disadvantages.

On the flip side, clear code is a competitive advantage. It allows teams to move faster, to respond more quickly to changing requirements and market conditions. It reduces the risk of introducing bugs when making changes. It makes the codebase more approachable for new hires, getting them up to speed and productive faster.

A study by Carnegie Mellon University found that teams with highly readable codebases had 32% higher productivity than teams with less readable code. Over the life of a project, that productivity difference can translate to significant savings in time and money.

In short, investing in code clarity is investing in your organization‘s ability to deliver value quickly and reliably. It‘s not just a best practice, it‘s a business imperative.

Conclusion

Writing clear, readable code is a skill that pays dividends over the entire lifecycle of a software project. By taking the time to choose clear names, decompose functions, write useful comments, and apply the other principles we‘ve covered, you can create code that‘s easier to understand, debug, modify, and extend.

Remember, the goal is not just to write code that works, but to write code that communicates its intent clearly. Always optimize for the reader, not just the writer, of the code.

By making code clarity a priority, you‘ll not only make your own development work easier, you‘ll also contribute to a codebase that‘s more maintainable, more agile, and ultimately more valuable to your organization. Happy coding!