“Clean Code”: High-level Principles

The Goal

The goal is to deliver software that is valuable, usable, and maintainable.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand”

-Martin Fowler

A codebase usually starts out as something simple and elegant. But over time, with added use-cases, requirements, deprecations, etc. the code easily becomes messy and confusing. You are often left wondering “who wrote this sh**?“; And sometimes the answer turns out to be you –your past, sloppy self .

To keep your code quality in-check, it’s important to invest time into code reviews. “WTFs per minute“ is my favorite way to gauge code quality.

There are plenty of great resources out there for understanding how to write high-quality code. This blog post is a list of high-level, general principles that I like to keep in mind while writing and reviewing code.

General Principles

YAGNI: You Aren’t Going to Need It

Have you ever written code for a future (theoretical) use-case? Stop that. You’re wasting time. Abstracting and optimizing code prematurely is a time waste because you’ll need to refactor later anyway.

The right time to abstract something is when you need to use it a second time.

Just build what you need when you need it.

DRY: Don’t Repeat Yourself

Have you ever found yourself copying and pasting chunks of code around from one file, class, or method to another? Time for a refactor. Duplicate code is a code smell and makes maintaining your code cumbersome.

Consider making a reusable private method or utils function instead.

KISS: Keep It Simple, Stupid

Have you ever over-engineered your code? Created layers of abstraction that you later regret? Don’t do that.

“Code is like humor: if you have to explain it, it’s bad.”
-Cory House

There are many situations, however, when abstraction and encapsulation makes the code cleaner and easier to maintain. Just don’t over do it.

Leave it better than you found it

Have you ever been working in a messy part of the codebase and thought “somebody should clean this up“? Clean it up! If you’re already touching that file take an extra 15 minutes to clean it up.

When I was a boy scout I was told to leave it better than I found it when adventuring in the great outdoors. We would clean other people’s trash at our campsite, on hiking trails, etc. –leaving it better for the next person. We should do the same with our software.

Don’t bite off more than you can chew though. The key is to make small improvements over time. How do you eat an elephant? One bite at a time.

Keep the codebase consistent

Have you ever seen a codebase with anti-patterns or too many patterns? Yeah, not very intuitive. Work with your team to establish patterns, linting rules, test coverage thresholds, etc. to keep things consistent.

It’s often a good idea to reference a style guide or create your own team-specific style guide.

You are an Author. Write code like one.

Have you ever searched for a bug in a codebase with huge methods that do way too many things? It sucks. You’re often forced to grok hundreds of lines of code just to find the bug and understand its context enough to fix it.

Your code should be easily navigable similar to books

A book can be easily navigated by starting high-level and digging deeper.
For example:

• Table of Contents → Chapter → Heading → Paragraph

A codebase should also be easily navigated by starting high-level and digging deeper.
For example:

• Namespace → Class → Public Method → Private Method

Each class and method should follow the Single-responsibility Principle, in other words: “do only one thing“. If your code follows this principle, then it will be self-documenting and easy to navigate.

Your code should read like a book

Read your code out loud. If it sounds bad and confusing, then it is bad and confusing.
For example, which of the following code snippets sound better when read out loud?

let burger
if (money > 6.00) {
  burger = true
} else {
  burger = false
}

let goingToBuyABurger =
  cashInWallet > 6.00

The one on the right sounds better to me and is more succinct.

Conclusion

Writing “clean code“ takes a lot more thought and effort than doing things the quick and dirty way. Just because something works doesn’t mean it should be shipped.

“Programming is the art of telling another human what one wants the computer to do”
-Donald Knuth

Sloppy code is a breeding ground for bugs. It’s best to take the time to write the code well. Your future self and other devs will thank you .