Read Time: 5.5 minutes

You know the feeling:

• Go through some code
• Think "Why the f🤬k is this so confusing"
• Spend hours figuring out what is happening

And sometimes you discover:

You wrote the code

ouch 🤕

Learning to write clean code comes with time, experience, and iteration.

After writing code for 13 years I have noticed the same patterns over and over.

Asking the right questions can save you hours of refactoring, pulling out hair, and sinking into a nihilistic worldview where nothing matters.

These are my 3 Principles for Clean Code.

Let's get into it:

Functions Do One Thing

Let's take the following function for example:

This function is called is_valid_phone_number_format

So when you call it you expect that it just returns whether the format is valid.

But this function does something else.

When the phone number is valid it also checks to see if the number belongs to an existing customer. It adds the phone number if it doesn't exist.

In general:

If you need to use the word "and" to describe what a function does, it can be broken up.

is_valid_phone_number_format returns a boolean indicating if the number passed in is a valid format AND adds it to the customer phone numbers if it was not already added.

The problem is this function does TWO functionally independent things.

The English word AND is a logical operator. Each function should be one piece of logic that can be utilized with a logical operator.

The root problem is that the logic was inverted from the approach. We need to approach it from a top-down approach instead of a bottom-up one.

Let's refactor the code:

After refactoring you can see that the main body of code handles the logic for us and reads pretty close to English:

If the number is a valid phone number add it to the customer numbers list

No side effects happening here to surprise anybody. Each function does precisely what it says it will.

Your goal when writing code should always be to make it read as close to english as possible.

That is the golden standard.

No Magic Values

Magic values can make code confusing and they are easy to avoid.

Assume the people who will read your code know nothing.

This will make everybody much happier. Even the people who have tons of knowledge about the system.

Don't make them look up something if they don't have to.

Take the following code for example:

Here we are checking if the user id is 12345 and returning True to give them access to the dashboard.

There are a couple of questions to ask here:

• What is significant about user ID 12345?
• Why do they have access to the dashboard?

You can avoid confusion by storing the ID in a variable with a nice name.

Here's how:

It is a very simple change to the code, but it clarifies a ton.

In the future, if somebody needs to check if the user id matches the admin else they have a variable right there to reuse.

At this point you might be thinking "Why not just leave a comment saying it is the admin ID?" and that leads me to the last point.

Comments are a last resort

In a majority of cases, code comments can be avoided.

I had a habit of writing lots of comments when I began programming and I realize now that it was a bad practice.

The main reason being:

Comments can lie. Code cannot.

It is possible that you write a comment, change some code around it, and then the comment is no longer true. It is impossible to do that with code unless you name a variable or function wrong.

Which one do you think is more likely to be caught in a code review?

Any time you reach for a comment you admit that you are failing to articulate yourself clearly with code.

______________________________________________________

Many of these ideas came from Clean Code by Robert C. Martin

A book that had a massive impact on my software career. I would suggest everybody picks up a copy and gives it a read.

Thank you all for reading. It means a lot ❤️

As always reply or email me at swdlodonnell@gmail.com with any questions. Even if it is just something small.

Have an amazing weekend ✌️