Daniel Azevedo

Posted on Nov 7

What is Clean Code?

#cleancode #cleancoding #architecture #python

Hi devs,
When developers talk about "clean code," they’re usually referring to code that is easy to read, understand, and maintain. Clean code isn’t just about making your code look nice—it’s about writing code that anyone in your team can pick up, understand, and modify without having to wade through endless comments or confusing logic. Writing clean code is about craftsmanship and adopting a mindset that values simplicity, clarity, and purpose.

In this post, we’ll explore the main principles of clean code, why it matters, and provide examples in Python to show how these ideas can be applied in practice.

Why Clean Code Matters

Readability: Code is more often read than written. Clean code ensures that it can be read and understood quickly by others (and by you in the future).
Maintainability: Clean code is easier to modify, fix, and extend without introducing bugs.
Scalability: Clean, modular code is easier to scale and adapt to new requirements.
Reduced Technical Debt: Messy code can lead to bugs, and each fix introduces more complexity. Clean code avoids this spiral by maintaining simplicity.

The benefits are obvious, but achieving clean code is a discipline. Let's look at the fundamental principles.

Key Principles of Clean Code

1. Meaningful Names

Names should communicate intent. Variable, function, and class names should clearly describe their purpose.

Example:

# Bad
def cal(x, y):
    return x * y

# Good
def calculate_area(width, height):
    return width * height

In the "bad" example, it’s unclear what cal, x, and y represent. In the "good" example, calculate_area, width, and height communicate purpose and make the code self-explanatory.

2. Single Responsibility Principle (SRP)

Each function or class should have a single responsibility or purpose. This reduces complexity and makes the code easier to understand and maintain.

Example:

# Bad
class Order:
    def calculate_total(self, items):
        # Logic for calculating total
        pass

    def send_order_confirmation_email(self):
        # Logic for sending an email
        pass

# Good
class Order:
    def calculate_total(self, items):
        # Logic for calculating total
        pass

class OrderConfirmationEmail:
    def send(self):
        # Logic for sending an email
        pass

In the "good" example, Order and OrderConfirmationEmail are responsible for different aspects of the application, following SRP.

3. Avoid Magic Numbers and Strings

Use constants or variables for any "magic" numbers or strings to make your code clearer and easier to modify.

Example:

# Bad
if user_age > 18:
    # Perform some action for adults

# Good
MINIMUM_AGE = 18
if user_age > MINIMUM_AGE:
    # Perform some action for adults

4. Keep Functions Small and Focused

Functions should do one thing and do it well. Avoid having functions that are long or do multiple tasks.

Example:

# Bad
def process_order(order):
    # Validate order
    # Calculate total
    # Send confirmation email
    pass

# Good
def validate_order(order):
    pass

def calculate_order_total(order):
    pass

def send_order_confirmation(order):
    pass

Each function in the "good" example does one specific task, making the code more modular and reusable.

5. Use Comments Wisely

Comments should explain "why," not "what." Code should ideally be self-explanatory; use comments sparingly and for context only when necessary.

Example:

# Bad
def multiply(a, b):
    # Multiply a by b
    return a * b

# Good
def calculate_discounted_price(price, discount):
    # Apply discount to the original price
    return price * (1 - discount)

In the "bad" example, the comment is redundant. In the "good" example, the comment gives additional context, explaining why we’re applying the discount.

6. Consistent Formatting

Consistent formatting, such as indentation and line breaks, improves readability. Follow a standard style guide like PEP 8 for Python, or define your team’s coding conventions.

Example:

# Bad
def foo():print("foo")

# Good
def foo():
    print("foo")

7. Error Handling

Handle errors gracefully. Code should anticipate potential errors, with clear error messages and recovery options.

Example:

# Bad
def open_file(filename):
    file = open(filename, 'r')
    content = file.read()
    file.close()
    return content

# Good
def open_file(filename):
    try:
        with open(filename, 'r') as file:
            return file.read()
    except IOError:
        print("An error occurred while opening the file.")

The "good" example ensures that errors are handled, and resources are properly closed.

The Mindset Behind Clean Code

Clean code requires a mindset that prioritizes simplicity, clarity, and empathy for other developers who will read and maintain the code. This mindset values practices that keep code concise yet informative, reducing unnecessary complexity and making the codebase more reliable and enjoyable to work with.

Wrapping Up

Writing clean code is an ongoing learning process, and it takes effort and discipline. Remember:

Name things clearly.
Keep functions small.
Follow the Single Responsibility Principle.
Handle errors gracefully.

Clean code might seem like extra effort, but the payoff in maintainability, collaboration, and future-proofing your work is invaluable. Embrace these principles, and you’ll be on your way to building software that not only works but is a joy to work with.

Let’s keep our code clean and our projects scalable!

Top comments (7)

Boopathi • Nov 7

This is a great overview of clean code principles! I especially appreciate the examples in Python - they make the concepts much clearer.

Stephen Dicks • Nov 8

I'm not convinced about your last example. You're swallowing the exception and converting it to a print (which will probably never be seen by anyone) so you've just made the situation worse.

Daniel Azevedo • Nov 8

I agree! Swallowing the exception and just printing it doesn’t help much — better to log it to a monitoring system or rethrow it to make debugging easier.

Tks :)