What Is Clean Code? Principles of Writing Clean Code and Examples

Writing code is one of the main jobs of developers. But have you ever considered writing clean code for ease of maintenance later? 

Writing code is like writing an article. You don’t just provide necessary information. But you should make it clear for your audience to read, understand, and even modify. 

This popularizes a concept known as ‘clean code’. 

So, what is clean code, exactly? How can you, as a software engineer, write clean code? 

This article will provide all the basics of this term. Let’s get started!

Understanding Clean Code

Briefly, clean code is the code that is easy to read, understand, and adjust. 

When writing code, you may want other peers to understand your purpose without further explanations. 

Also, as the author, you may feel overwhelmed when looking back at your complex, poorly-organized code for maintenance or updates. This is where clean code shines. 

Without complex or redundant details, clean code allows your team to track the logic easily. It complies with best practices and established conventions. 

For this reason, it enables your team to collaborate seamlessly, increase productivity, and reduce issues (e.g., syntax errors or bugs). 

Clean code includes the following key characteristics:

Clean code is free from complicated logic. Instead, the code is easy to understand, test, maintain, and scale for both authors and other developers. This makes your codebase more reliable.

Clean code often uses consistent structuring and naming for variables, functions, and classes. This makes the code readable and reflects its meaning directly without further explanation. 

In clean code, related parts are clustered logically. The code also adheres to consistent architecture, formatting, and indentation. This helps your team easily navigate around the codebase and maintain the code efficiently. 

Clean code itself tells what it does. It doesn’t need comments to talk about its purpose anymore. Instead, comments should clarify why something exists or happens. For this reason, your team may easily trace back to the code that fails to work or needs updates. 

Examples of Clean and Unclean Code

The examples below give you a better understanding of how clean code looks in reality. We also compare it with unclean code and explain why. 

Accordingly, we write the Python code to calculate the dot product of two lists and only cover positive values from the first list. 

Unclean Code

def d(a, b):

    r = 0

    for i in range(len(a)):

        if a[i] > 0:

            r += a[i] * b[i]

    return r

The code above is unclean as it has poor naming. No one may understand what d, a, b, and r mean except for the author. Further, no comment or docstring is given to clarify the code’s purpose. 

Further, the code doesn’t explain why it only includes positive values from a (the first list). Other developers may feel confused about this command and wonder whether this filtering is intentional or significantly affects the calculation.  

Clean Code

def positive_dot_product(vector_a, vector_b):

    """

    Calculate the dot product of two vectors,

    including only the positive elements of the first vector.

    """

    if len(vector_a) != len(vector_b):

        raise ValueError("Vectors must have the same length.")

    result = 0

    for index in range(len(vector_a)):

        if vector_a[index] > 0:

            result += vector_a[index] * vector_b[index]

    return result

Now, look at the code above. It’s clean, as its naming looks meaningful. positive_dot_product, vector_a, vector_b and result show readers exactly what they reflect. 

The function name positive_dot_product also explains that choosing only positive values from vector_a is intentional. 

Further, the code also describes its purpose and logic through concise docstrings. 

The Importance of Writing Clean Code

Since being made popular in 2008 by Robert C. Martin, clean code has become an important norm in developer circles. It comes with various immersive benefits, especially for long-term projects:

• Effective team collaboration

You don’t write code for yourself to read, but for other developers and even your future self to understand and update. 

If your code is messy, your team members may take hours or days to fix it. Even you struggle to extend or upgrade the functionality of inefficient, hard-to-read code in the future. Besides, onboarding new members on such code is challenging. 

But clean code allows developers to collaborate smoothly, learn faster from others’ work, and contribute with more confidence. 

Clean code offers clear formatting, meaningful variable names, and sufficient documentation. This helps your team easily grasp specific parts of the codebase and locate issues for debugging. 

• Ease of maintenance & update

Clean code focuses on clear naming, well-defined structure, and proper commenting. This helps other developers interpret the functionality and purpose of your code and extend the code more efficiently.

To write well-structured code, you need to comply with established coding standards and best practices. These practices improve your code’s quality, reduce technical debt, and increase the overall reliability of the finished product. 

• Reduced resources (maybe)

Clean code eliminates unnecessary operations or complex logic. It uses clear, straightforward logic instead. Therefore, it often runs faster and consumes fewer resources. 

But sometimes, clean code may work more slowly. It prioritizes readability and maintainability. So its clear variable names, readable loops, or well-defined functions may add a bit of overhead. 

Is Clean Code Still Relevant?

Yes, clean code and its code principles are still essential in today’s era, although people have different views about it. 

Some developers consider clean code a bliss, reducing their work hours on refactoring or debugging code. Especially when you intend to reuse the code or when issues become more complex, well-structured code can save you much time and effort. 

However, clean code also receives lots of criticism from other developers. Cleaning up code may slow down your development process. 

Think of it like cleaning your house. Not many people want their houses to be flooded with trash. But cleaning up too often can overwhelm them and eat up much of their time and effort. 

The same also applies to cleaning code. Therefore, in some contexts, you should prioritize a working solution over a perfectly clean structure. 

Having said that, readable code is still crucial:

• It reduces technical debt and business risks in many projects. 
• Writing clean code may initially cost a little time, but your team can fix bugs, onboard new developers, and accelerate future work faster with such code. 
• Modern developer tools (e.g., code review bots or linters) work better with well-structured code. Especially, if you plan to use AI coding assistants, keeping code clean helps them suggest safer and more accurate outputs. 

Core Principles of Writing Clean Code

You want to write readable code for later maintenance or easy reuse? If so, you need to follow the core principles to write clean code efficiently. In this section, we’ll list out nine important principles you should consider, plus examples using Python. 

Replace Hard-Coded Values with Named Constants

Sometimes, you’ve got these fixed values lurking in your code, like numbers, strings, whatever. For example, when you embed $1000 and 0.25 directly into the source code, these values are what we call “magic numbers” or “hard-coded values.”

And the problem here is pretty obvious, right? Except for you, the original author, no one will understand what those values reflect. 

That’s why you need to give them named constants. This helps you immediately explain what they actually mean and reduce the mental load for everyone. 

Here’s an example:

Unclean Code

if price > 1000:

    discount = price * 0.25

Looking at this code, you may ask, “What do 1000 and 0.25 represent? Why does the author use these values here?” This confusion makes it hard to check the issue in the code.

Clean Code

MAX_ELIGIBLE_PRICE = 1000

DISCOUNT_RATE = 0.25

if price > MAX_ELIGIBLE_PRICE:

    discount = price * DISCOUNT_RATE

By giving these fixed values a name, you help other developers read the code easily. Accordingly, they understand 1000 as the highest price eligible for the discount, while 0.25 is clearly the discount percentage. 

Use Meaningful, Descriptive Names

Similarly, when you’re naming variables, functions, classes, or anything else in your code, their name really ought to reflect their meaning or ultimate purpose without needing a separate comment block to explain it.

Giving them descriptive, meaningful names helps other developers immediately grasp what that block of code is doing, you know? 

It potentially saves them a ton of time guessing their function or wading through documentation.

Here’s an example:

Unclean Code

def calc(x, y):

    return x * y

If your code contains many different calculations for taxes, profits, or something else, writing calc may mix these calculations up. Besides, your colleagues may not understand what x or y here means and take time to guess their functionality. 

Clean Code

def calculate_tax(subtotal, tax_rate):

    return subtotal * tax_rate

By describing variables and functions clearly, you let others know that you want to calculate tax here. Of which, the inputs include the sum of a specific product line (subtotal) and the tax rate (tax_rate). 

These descriptive names improve code readability, reduce confusion, and make code maintenance easier. 

Using comments is a good way to explain your code. But over-commenting complicates your codebase and makes it hard to track truly important functions. 

Therefore, clean code often uses descriptive names to let variables, functions, and classes explain their purposes themselves. 

Besides, they only include comments that add real value and focus on explaining why the code works in that way. Accordingly, you should leverage comments to interpret complex algorithms, unusual logic, design decisions, or anything unclear in the code. 

Here’s an example:

Unclean Code

# Add 1 to counter

counter = counter + 1

This comment sounds redundant. It restates the functionality of the code while adding no extra value.

Clean Code

# Adding 1 to counter to handle the initial login attempt

counter = counter + 1

This comment explains the intent or reasoning behind the code. This allows other team members to understand why this function is implemented. 

Write Small, Focused Functions

There’s that old saying: “Jack of all trades, master of none.” And I think that really applies here. 

Instead of trying to develop some overly versatile function that does different things, I mean, you should focus on writing a short block of code that takes a single responsibility. In other words, it should perform one well-defined task excellently.

This idea comes straight from the Single Responsibility Principle (SRP). 

This definitely allows your team to easily identify exactly what the function aims at, hence simplifying testing and maintenance. 

Further, it’s much easier, kind of naturally, to reuse these focused functions in other parts of the software. It just makes sense. 

Here’s an example:

Unclean Code

def process_order(order):

    validate_order(order)

    charge_credit_card(order)

    send_confirmation_email(order)

    update_inventory(order)

Looking at this function, you may struggle to understand it at first glance. Adding four different tasks (order validation, payment, email notification, and inventory update) means you hardly test everything and identify which part results in issues. 

Clean Code

def process_order(order):

    validate_order(order)

    charge_credit_card(order)

    send_confirmation_email(order)

    update_inventory(order)

def validate_order(order):

    # validation logic here

def charge_credit_card(order):

    # payment logic here

def send_confirmation_email(order):

    # email logic here

def update_inventory(order):

    # inventory logic here

In this code, each function is assigned a single role. This helps you identify what it aims to and test the functions independently. If you want to make any adjustments, it’s also much easier to locate the specific function responsible for what you want to improve. 

Follow the DRY Principle – Don’t Repeat Yourself

This principle highlights that you shouldn’t write the same code or logic many times. 

In other words, you should turn the same code into functions, classes, or any abstractions for reuse. This keeps your codebase readable, easier to maintain, and consistent. 

Further, duplicated code can lead to a higher risk of errors – for example, you update one code but forget another. Therefore, reusing the same logic not only reduces this risk but also allows other developers to understand the logic better. 

Here’s an example:

Unclean Code

# Applying discount for regular customers

final_price = total_price - (total_price * 0.1)

# Applying discount for premium customers

final_price_premium = total_price - (total_price * 0.2)

This code is unclear because it repeats the logic for applying discounts. What if you want to change the formula for calculating discounts? 

You have to update it in many places in the program. Not only does this waste time, but this can also lead to mistakes if you forget to update one certain place.  

Clean Code

def apply_discount(total_price, discount_rate):

    return total_price - (total_price * discount_rate)

final_price = apply_discount(total_price, 0.1)

final_price_premium = apply_discount(total_price, 0.2)

To make the code cleaner, you only need to wrap the discount logic inside a function and reuse it in multiple places. 

Adhere to Established Coding Standards

Each programming language has its own coding style and conventions. These standards tell you how to name variables, format code, structure files, or write comments. 

For example, Python developers name and format variables, functions, and classes using snake_case (e.g., user_id) or leverage spaces – not tabs – for indentation.  

Following coding standards keeps code predictable, readable, and consistent. Instead of guessing what the code reflects, everyone in your team can read it without confusion and collaborate smoothly on the same codebase. 

Encapsulate Nested Conditionals

A nested conditional technique allows you to place a conditional statement (if, else if, else) inside another one. This allows the inner condition to be evaluated only if the outer layer is true. 

But what if your code has too many layers of conditional statements? This time, the code is hard to read, as your eyes have to look through multiple conditions to identify what the code truly does or find errors if the code doesn’t work. 

As a result, this can slow down your development or debugging. 

To address this issue, wrap nested conditionals into a function and give it a meaningful name. This not only improves readability and maintainability, but also helps you check what the conditions do. 

Here’s an example:

Unclean Code

def calculate_product_discount(product, user):

    if user.is_member:

        if product.category == "electronics":

            if product.price > 500:

                return product.price * 0.10

            else:

                return product.price * 0.05

        else:

            if product.price > 100:

                return product.price * 0.03

            else:

                return 0

    else:

        if product.category == "electronics":

            return product.price * 0.02

        else:

            return 0

This code contains too many nested conditionals, making it hard to understand, test, and update the logic later. 

Clean Code

def get_discount_rate(product, user):

    if user.is_member:

        return _member_discount(product)

    return _non_member_discount(product)

def _member_discount(product):

    if product.category == "electronics":

        return 0.10 if product.price > 500 else 0.05

    return 0.03 if product.price > 100 else 0

def _non_member_discount(product):

    if product.category == "electronics":

        return 0.02

    return 0

def calculate_product_discount(product, user):

    discount_rate = get_discount_rate(product, user)

    return product.price * discount_rate

By putting nested blocks into different functions, you give them a clear purpose. This allows developers to understand the complex logic inside each function and make future changes more easily. 

Continuously Review and Refactor Your Code

Your room looks messy. And you need to clean or reorganize stuff around to make your room neater. 

The same applies to your code, and that process is called “refactoring.” It doesn’t involve adding new functionality to your codebase, but arranging the inner structure. 

Frequently reviewing and refactoring your code makes its inner structure easier to understand and maintain. Even when new developers want to contribute to your codebase or when your future self wants to look back at it, no one will feel confused by messy code. 

This makes those working on the codebase more productive in the long run, reduces bugs, and removes unnecessary complexity. 

Manage Your Work with Version Control Systems

The final core principle of writing clean code is using version control like Git to create a safe and well-organized development environment. 

Version control systems help you track changes in your code efficiently and roll back to previous versions. For this reason, you can refactor and debug safely. 

For example, if you rearrange the code to create a new structure but find it wrong, you can instantly revert to a cleaner or better version of the code. 

Further, through version control, developers may understand why some snippets of code are created in that way. This helps them grasp the code and avoid old mistakes.  

Besides the core principles we discussed above, you should combine automated tools with hands-on practices to ensure the quality and cleanliness of your code.

Tools

Using the following automated tools, you can better comply with style guides and detect common errors early. 

• Code Linters: Automatically check where your code has stylistic issues and adheres to specific coding standards (e.g., naming conventions or line length). Example: ESLint for JavaScript/TypeScript, Pylint for Python, RuboCop for Ruby.
• Code Formatters: Automatically fix many of the above issues to make your code cleaner. Example: Black for Python, Prettier for JavaScript, gofmt for Go.
• Static Code Analysis Tools: Analyze your code to spot quality issues, potential defects, code complexity, and security flaws. Many of them are integrated into your CI/CD pipelines to stop building working software if your code doesn’t meet quality requirements. Example: SonarQube, Codacy, PMD, Coverity, Snyk.
• Testing Tools: Test whether your code is stable, readable, and predictable. They reveal unclear logic, discover hidden dependencies, and encourage you to write focused, clean code. Example: Jest, Pytest, JUnit.

Human-Driven Practices

Adopting the following practices, you can easily discover poor structure and logic issues:

• Review code by following coding style standards and architectural principles that other developers can reference. Further, you should keep reviews small (under 400 lines of code is ideal) to avoid fatigue and make thorough reviews. You should also offer constructive feedback on the code by reviewing its true intent and internal structure. 
• Use shared configuration files, like EditorConfig, to enforce the same settings for style (e.g., tab width) and quality standards for all developers’ IDEs. 
• Leverage pair programming and focused group sessions (coding dojos) to discuss and practice clean coding techniques. 
• Schedule regular reviews and refactoring to prevent technical debt and improve important functions. 

Conclusion

This blog post highlights the significance of writing clean code. Despite some criticism about its waste of time, keeping code readable allows other developers to continue your work, detect issues early, and update the software easily. 

If you want to make that commitment but lack specialized expertise, partner with a dedicated tech company. 

Here at Designveloper, we offer specialized IT consulting and development services. Our highly skilled developers and designers work alongside your team to deliver readable, scalable code for long-term projects. 

We adopt robust coding standards for different programming languages and help you build a strong culture of engineering excellence. With our commitment to engineering excellence, our code is easy to understand, debug, and maintain. 

Over years of operations, we have implemented 200+ successful projects across domains, typically LuminPDF, ODC, Boon, and Switchboard. Our solutions have received positive feedback from both clients and end users for their ease of use and maintainability.  

Contact us now to get a detailed consultation for your project! Let’s bring your idea to life!