5 Clean Code Tips for Self-Taught Developers

Before we dive in, if you are new to programming, there is a lingo section in the bottom of this blog to catch up on some terms I'll use in this article. Throughout the piece, I'll also have the first instance of each anchor-linked, clickable, and underlined. :)

At the start of my career, I had one simple programming goal: GET. IT. TO. WORK. If my scripts ran and the output was as expected, it was a success in my book. But as time went on and I began working on bigger projects and collaborating with others on shared repositories, I realized that how the code is written matters just as much as whether it works. 

I wanted to learn how to develop code that I could maintain months later, how to create successful merge requests with a fraction of the review comments, and how to grow functionality without starting from scratch each time.

I didn't know it at the time, but I wanted to learn everything I could about clean code.

What is Clean Code?

Clean code is code that is easy to read, understand, and update. It is written clearly, organized thoughtfully, and structured in a way that helps everyone follow what it’s doing.

Why Clean Code Matters

At first, the principles behind clean code can feel a bit like perfectionistic overkill and a waste of time. But in reality, clean code ends up being a huge timesaver in the long run and a gift to the next person reading it (which, let's be honest, often ends up being yourself). 

When code is well-written, it is easier and quicker to debug, test, change, and extend. Code comments can help, but the code itself is the ultimate source of truth of what is happening. The clearer that truth is, the more maintainable your project will be and the better it will hold up over time. Clean code not only encourages people to collaborate with you, but also makes it far less overwhelming for your future self to revisit and work on.

How to Start Writing Cleaner Code

Learning how to write cleaner code takes time, but luckily, even small shifts in your habits can make your code much easier to read, test, and maintain in the future.

Here are the top clean coding principles that have helped me the most:

1. Write small, focused functions that are written to be tested. In general, smaller functions reduce complexity and make debugging or updating easier, because each part does one thing clearly.

# Before
def process_temperatures(degrees_fahrenheit):
    # Convert all values to Celsius
    celsius_values = []
    for d in degrees_fahrenheit:
        c = (d - 32) * 5 / 9
        celsius_values.append(c)

    # Calculate average Celsius temperature
    average_celsius = sum(celsius_values) / len(celsius_values)

    # Print summary
    print(f"Average temperature in Celsius: {average_celsius:.2f}")
    print(f"Converted values: {celsius_values}")

# After
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

def calculate_average_degrees_celsius():
...

2. Use descriptive variable, function, and argument names. Clear names make your code self-explanatory, so others (and future you) don’t have to guess what a function or argument means. So, no more one-letter variable names, and if it's applicable, add the expected units in variables, arguments, and functions.

# Before
def conv(x):
    return (x - 32) * 5 / 9

# After
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

3. Be consistent. If the same concept appears in multiple places, use the same name for it across your codebase so you don't have to remember what way to refer to it when and where.

# Before
degrees_fahrenheit = 68 
FahrenheitDegrees = 75
degrees_in_fahrenheit = 70

# After
degrees_fahrenheit_1 = 68 
degrees_fahrenheit_2 = 75
degrees_fahrenheit_3 = 70

4. Don't repeat yourself (DRY). Repeating lines or blocks of code opens up more room for bugs and it's harder to maintain.

# Before
degrees_fahrenheit_1 = 68 
degrees_fahrenhiet_2 = 75
degrees_farenheit_3 = 70

degrees_fahrenheit = [degrees_fahrenheit_1, degrees_fahrenheit_2, degrees_fahrenheit_3]

# After
degrees_fahrenheit = [68, 75, 70]

5. Avoid hard-coding constants. Define them at the top of your script or store them in a separate constants file for easier changes and a reduced risk of missing a change (particularly when constants are repeated).

# Before
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

# After
FAHRENHEIT_FREEZING_POINT = 32
FAHRENHEIT_TO_CELSIUS_RATIO = 5 / 9

def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - FAHRENHEIT_FREEZING_POINT) * FAHRENHEIT_TO_CELSIUS_RATIO

The more small improvements you make today, the easier your code will be to work with tomorrow. And the easier it is to work with, the more you will enjoy programming, helping you to code more, learn faster, and build projects that last.

So now, before you embark on your clean coding adventure, I want to leave you with one final tidbit: I have written bad code. You will write bad code. At some point, you will write it thinking that it is good code, only to find head-shaking inefficiencies and humbling room for improvement later.

I want to let you know that if you find yourself there, IT'S OKAY! Every revisit to your code is a chance to refactor, refine, or remove what’s no longer needed. In fact, if you feel cringe or embarrassed looking at your old code, it's more than okay...it's great! It just means you've grown as a developer, and that's never something to be ashamed of.

🌟 Enjoyed this post? Join my email list for new maps, blog updates, and cartography tips.

Decoding the Lingo in this Blog

• Merge request (MR) - A request to merge your code changes into a shared codebase in Gitlab (for Github it's called "Pull Request"). Your collaborators review your work before it becomes part of the main project.
  

• Review comment - A comment made during a merge request by someone reviewing your code. It might point out bugs, suggest improvements, or ask clarifying questions.

• Debug - The process of finding and fixing "bugs" (errors or unexpected behavior) in your code.

• Test / Testing - Writing code that automatically checks whether your functions behave as expected. Helps you catch bugs early and prevents broken code from slipping into production.
  

• Code comment - A short explanation written directly in your code (using # in Python, // in JavaScript, etc...) to help give others more context to your code when reading it.

# I am a comment!

• Function - A reusable block of code that performs a specific task. Functions usually take inputs (arguments), do something, and return a result.

# Example function below
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

• Variable - A name that holds a value, like a label for data in your program.

# degrees_fahrenheit is the variable
degrees_fahrenheit = 68 

• Argument - A value you pass into a function when calling it. For example, in convert_to_fahrenheit(temperature), temperature is the argument.

# degrees_fahrenheit is the argument
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

• Constant - A value that doesn’t change throughout your script.

# 32, 5, and 9 are all constants here
def convert_degrees_fahrenheit_to_celsius(degrees_fahrenheit):
    return (degrees_fahrenheit - 32) * 5 / 9

• Refactor - Rewriting or reorganizing code to improve its structure or readability, without changing what it actually does.