Article

10 steps to clean code

Clean code is a reader-focused development style that produces software that's easy to write, read and maintain. Often, you may be tempted to consider your work complete when the application operates as expected. But we're not merely writing code for computer consumption.

Clean code is about recognizing that your audience isn't just a computer, it's real-live humans! With this principle in mind, let's review the reasons clean code matters and dive into some tips and tricks when it comes to how we can do it in practice.

Here’s why keeping your code clean matters

It's foundational

Clean code principles lead to source code that's highly modular and thus easier to read and test. If you think of these practices as part of a house, clean code is the foundation. Implementing clean code principles is a foundational skill that pays off especially well when it's time to refactor code or bring code under test. 

 

There are three core principles to remember when it comes to writing clean code:

  1. Choose the right tool for the job

  2. Optimize the signal-to-noise ratio

  3. Strive to write self-documenting code

Reading is hard

Let’s call it how it is: Writing code is relatively easy. Reading is hard. This is why it is so tempting to rewrite rather than do the hard work of reading and comprehending existing code. Since reading code is naturally challenging, if you write code that you're barely able to follow as you write it, you'll find you're unable to comprehend it all later.

Technical debt is depressing

Writing sloppy or confusing code injects technical debt into projects. And while technical debt can be useful when carefully considered in context, excessive technical debt is depressing. You’ll likely derive more job satisfaction out of the quality of your work than the quantity. History has shown it's unlikely you'll find time to clean it up later, so why not do it right the first time?

No one wants to be a verb

Okay, the other reasons are solid, but this one is the clincher: Everyone knows the previous co-worker whose name became a verb to describe dirty code.

 

"Oh man, this code has been Jimmy'd."

 

Ouch. Comments like this are the kiss of death for long-term employment prospects. We want our co-workers to recommend and hire us in future positions, right? Being known for writing clean code is a great way to assure your co-workers recommend you and look forward to working with both you and your code in the future.

Here’s how you can start writing cleaner code today

Now that we’ve covered why clean code matters, let’s get down to the practice of it. Here are a few ways you can ensure your code comes out clean.

1. Conventions

Using a naming convention is a great way to get started — it keeps things clear and lets you know exactly what you’re working with. 

 

A naming convention basically means you decide you’ll call your variables by names that adhere to a certain set of rules. It can get hairy, and a lot of people don’t always agree on which is best. So to keep it simple. It can be something as simple as prefixing variable names with their data type, like this:

MyIntiger Code Snippet

2. 360 no scope

The next thing, which follows nicely from using naming conventions, is using a convention to indicate variable scope. Again, there are no rules, and everyone has their own way of doing it — as long as it’s consistent throughout all of your code, it will always be clear what can be used from where.

A common convention goes as follows:

360 no scope code snippet

3. Say what you mean

This is pretty straightforward, but it’s probably the most common and maybe the easiest one to forget. Easily the most frustrating thing for another developer looking at your code is seeing a variable with a misleading name or, worse, named with a single letter. 

Let’s take a look at an example of this:

variable with a misleading name

While this might look okay, and it is functional, if someone found this in a sea of code with no comments, it isn’t clear why any of it is happening at all. 

4. Whitespace is nice space

Using whitespace can be incredibly powerful and normally has absolutely no downside. Sometimes in languages like JavaScript where the file size of the source code itself is important, you might want your files to be small, and that whitespace can add a few extra kilobytes. When you can, keep all your whitespace during development so the code is readable. Then, use one of the many smart little programs that go through code and chop out all the whitespace just before you upload it.

5. Commenting saves lives — or at least headaches

Adding comments to your code can be invaluable—they can quickly show what a complex function is doing, or maybe even explain why certain things need to happen in a certain order. They do have a downside, though, because too much commenting can have the opposite effect and actually make for messier code.

6. Automate after three times

Writing slightly more technical code doesn’t mean it has to be less readable. Lines and lines of duplicate code are not only harder to read than a concise and elegant solution, but they also increase the chance for error. The great thing about programming is that you can express complex commands in tidy, reusable, and clever ways.

Here’s an example of poor, duplicated code:

Duplicated Code Snippet

And here’s an approach that cleans everything up:

Clean code snippet for duplicated code example

7. The power of i

When you have a code block with multiple loops one after the other, you need different iterator variables. There is always debate about what to use, and the answer is slightly subjective, but when they’re one after another, it makes sense to declare your iterator outside of the loop and reuse it. It’s not only better to look at, as it’s always clear that “i” is your iterator variable, but it’s also slightly more efficient.

Let’s look at an example of what I’m talking about:

declare your iterator outside of the loop and reuse it

8. Birds of a feather flock together (and they group similar variables)

When your projects start to get larger, your classes will likely have many variables. First, you should be keeping all of your variable declarations at the top of the page, or at the very least all together somewhere—this speeds up any kind of searching.

Second, even though they are all together, it often helps to arrange them in such a way that makes them even easier to comprehend. For example, grouping them all by what they are is a good way to go. It’s quite likely that you’ll have several types of the same object, so keep those all together in groups, and then maybe have a section for the miscellaneous ones underneath.

9. Keep it functional

Mile-long function definitions are an easy way to clutter your code. Normally it’s best to take a look at what’s actually being done. If a function is doing more than its name suggests, then perhaps some of the excess functionality could be split out into its own function.

10. Keep it classy

Similar to the functional problem, if there’s a large amount of functionality you’re keeping all in one place, it could be better to create a separate class to handle that functionality.


When it comes to writing, reading and maintainability, clean code is essential. The steps outlined above are not concrete rules. Use them as outline, or use them as a guide to find your own style and way of doing things. The important thing is this: Keep it tidy, clearly sectioned, and consistent. Anyone working with your code will appreciate the effort, and might even learn something from your example.