MNW #046: 8 Tips To Write Clean Code

Read on milanjovanovic.tech​
​
​Read time: 5 minutes
​

A big thank you to our sponsors who keep this newsletter free to the reader:

Today's issue is sponsored by Pluralsight. Pluralsight's 2023 State of Cloud report comes with some surprising findings. Did you know 70% of organizations have more than half of their infrastructure in the cloud? Or that 44% of organizations adopt the latest cloud products as soon as they're available? Find out where you stand in the industry - and how to get ahead.​

And by IcePanel. IcePanel realigns your engineering & product teammates on the technical decisions made across the business. Explain your complex software systems with an interactive map that teammates can drill down to the level of detail they need.

Clean code is code that's easy to read, maintain, and understand.

I consider writing clean code a skill.

And it's a skill that you can learn and improve with deliberate practice.

My favorite approach for practicing clean coding is doing refactoring exercises.

So I prepared one for you today, and we're going to improve it one step at a time by applying clean code principles.

Let's dive in.
​

Starting Point

I like starting with a problem when trying to learn new concepts.

And the more illustrative the problem, the better.

So we'll use some poorly written code as the starting point for our refactoring.

And in each step, I will highlight what the current issue is and how we will fix it.

Here's what I see when I look at the Process method:

• Deep nesting of code - 4 levels, to be precise
• Precondition checks are applied one after the other
• Throwing exceptions to represent a failure

How can we turn this into clean code?

​

#1: Early Return Principle

It should be painfully obvious by now that the initial version is deeply nested because of the if statements applying precondition checks.

We'll solve this using the early return principle, which states that we should return from a method as soon as the conditions for that have been met.

In the case of the Process method, this means moving from a deeply nested structure to a set of guard clauses.

​

#2: Merge If Statements To Improve Readability

The early return principle makes the Process method more readable.

But there's no need to have one guard clause after another.

So we can merge all of them into one if statement.

The behavior of the Process method remains unchanged, but we remove a lot of excess code.

​

#3: Use LINQ For More Concise Code

A quick improvement can be using LINQ to make the code more concise and expressive.

Instead of checking for Items.Count == 0, I prefer using the LINQ Any method.

You could argue that LINQ has worse performance, but I always optimize for readability.

There are far more expensive operations in an application than a simple method call.

​

#4: Replace Boolean Expression With Descriptive Method

Merging multiple conditions into one if statement means writing less code, but it can decrease readability with complex conditions.

However, you can fix this and improve readability by using a variable or method with a descriptive name.

I prefer using methods, so I will introduce the IsProcessable method to represent the precondition check.

​

#5: Prefer Throwing Custom Exceptions

Now let's talk about throwing exceptions. I like to use exceptions for "exceptional" situations only, and I don't use them for flow control in my code.

Having said that, if you do want to use exceptions for flow control, it's better to use custom exceptions.

You can introduce valuable contextual information and better describe the reason for throwing the exception.

And if you want to handle these exceptions globally, you can create a base class to be able to catch specific exceptions.

​

#6: Fix Magic Numbers With Constants

A common code smell I see is the use of magic numbers.

They are usually easy to spot because they're used to check if numeric some condition applies.

The problem with magic numbers is that they carry no meaning.

The code is harder to reason about, and more error-prone.

Fixing magic numbers should be straightforward, and one solution is introducing a constant.

​

#7: Fix Magic Strings With Enums

Similar to magic numbers, we have the magic strings code smell.

A typical use case for magic strings is to represent some sort of state.

You'll notice that we're comparing the Order.Status value to a magic string to check if the order is ready to process.

A few problems with magic strings:

• Easy to make mistakes (typo)
• Lack of strong typing
• Not refactoring proof

Let's create an OrderStatus enum to represent the possible states:

And now we have to use the appropriate OrderStatus in the check:

​

#8: Use The Result Object Pattern

I said I don't prefer using exceptions for flow control. But how can we fix this?

One solution is using the result object pattern.

You can use a generic Result class to represent all types of results or a specific one like ProcessOrderResult.

To make your result objects encapsulated, expose a set of factory methods to create the concrete result type.

Using an enum like ProcessOrderResultType will make consuming the result object easier with switch expressions. Here's the enum to represent the ProcessOrderResult.Type:

And now the Process method becomes:

Here's how using an enum for the ProcessOrderResult.Type allows you to write a switch expression:

​

Takeaway

That's it, 8 tips to write clean code:

• Early return principle
• Merge multiple if statements
• Use LINQ for conciseness
• Replace boolean expression with method
• Prefer throwing custom exceptions
• Replace magic numbers with constants
• Replace magic string with enums
• Use the result object pattern

Writing clean code is a matter of deliberate practice and experience.

Most people will read about clean coding principles, but few will strive to apply them daily.

This is where you can set yourself apart.

I also made a video about these clean code tips, you can watch it here.​

Hope this was helpful.

See you next week!

Today's action step: Take a look at your project and see if you're making some of the mistakes I highlighted here. And then fix them using the clean code tips I shared with you.

Whenever you're ready, there are 2 ways I can help you 🎁

1. If you're looking to join a community of like-minded engineers, or you want to access all of the source code that I use in my YouTube videos, you can do that by becoming a Patron. Join 750+ engineers here.​
   ​
2. Promote yourself to 24,000+ subscribers by sponsoring this newsletter (booked out 2 months)