The Importance of Clean Code!

Imagine this scenario: your friend just finished his task and asked you to review his code. As you dive into his work, you realize you can’t make sense of it. The code works, but it’s a confusing jumble.. Frustrated, you wonder why it’s so hard to understand. The problem? The code isn’t clean.

Or consider another situation: you write a piece of code for a project. Two weeks later, you revisit your own work to complete another part of the project. To your surprise, you can’t decipher what you wrote. It’s like looking at someone else’s code for the first time. Annoying, right?

These scenarios highlight the critical importance of clean code. While code may function correctly, its readability, maintainability, and extendability are equally important. Clean code practices can make a world of difference.

What is Clean Code?

"Clean code is simple and direct. Clean code reads like well-written prose" — Robert C. Martin, _Clean Code

- Simple: It’s straightforward and does not include unnecessary complexity.

- Easy to Read: Anyone can understand it without much effort.

- Easy to Modify: Changes can be made easily without breaking other parts of the code.

Why is Clean Code Important?

"Indeed, the ratio of time spent reading versus writing is well over 10 to 1” — Robert C. Martin, Clean Code

developers spend much more time reading code than writing it, which makes clean code crucial. In fact, they spend much more time understanding and navigating existing code than actually writing new code. This makes clean code crucial for several reasons:

1. Maintainability

Clean code is easier to maintain and extend. This reduces the time and effort needed to fix bugs or add new features.

If you come back to the code later on, even after a long time, you can easily understand what it's supposed to do and make changes without causing any new problems or mistakes.

2. Collaboration

When multiple developers work on the same codebase, clean code ensures that everyone can understand and work with the code efficiently.It's like having a common language that everyone can easily grasp, making teamwork smoother and more productive.

3. Reliability

Clean code is like a well-built machine; it's easier to test and debug, ensuring that the software operates smoothly and reliably.

Introduction to Clean Code Principles

Clean code has basic rules to follow. You can find these rules in books or online. Let me share a few simple ones with you. If you already know them, feel free to skip ahead. But if not, these will give you an idea of what's to come and might even make you curious to learn more.

Basic Rules:

1. Logical Positioning: Arrange your code logically to enhance its readability and maintainability.
2. Logical Names: Use meaningful and intuitive names for variables, functions, and classes.
3. Short Functions: Write functions that perform a single task and are concise, making them easier to understand and maintain.
4. DRY (Don't Repeat Yourself): Avoid duplicating code by abstracting common functionality into reusable components.
5. Readability: Strive to write code that reads as close to English as possible, making it easy for others to understand and collaborate.

Understanding Clean Code Principles: Source code structure

• Separate concepts vertically.
• Related code should appear vertically dense.
• Declare variables close to their usage.
• Dependent functions should be close.
• Similar functions should be close.

Personally, to determine if my code is in a good position, I ask myself:

Will I remember to look for a file named X in a folder named Y?

Will I be able to find the function X in file Y?

Example:

• Root:
• Src:
• ■ main.py
• ■ math_func.py
• utils
• Settings

● Is this a good positioning?

if you are using a functions or a variable in place X, doesn't mean that you need to define it at this place.

Understanding Clean Code Principles: Names rules

1. Choose Descriptive Names
2. Use Pronounceable Names
3. Use searchable names.
4. Replace magic numbers with named constants.
5. Avoid encodings. Don't append prefixes or type information

Example:

Non-Descriptive Naming:

What does 'p' represent?

double p;          

Descriptive Naming:

The name clearly describes that this is a price in dollars.

double priceInDollars ;         

Understanding Clean Code Principles: Comments rules

1. Explain with code: Write code that's easy to understand on its own, without needing lots of comments.
2. Avoid repeating yourself: Don't write the same thing multiple times. Keep your code short and sweet.
3. Keep it clear: Don't clutter your code with unnecessary stuff like extra comments or blank spaces.
4. Skip closing brace comments: Instead of commenting on every closing brace, focus on making your code neat and tidy.
5. Delete unused code: If you don't need it, just get rid of it. Don't leave old code lying around—it just gets in the way.

Understanding Clean Code Principles: Functions rules

1. Do one thing.
2. Use descriptive names.
3. Prefer fewer arguments.
4. Don't use flag arguments. Split method into several independent methods that can be called from the client without the flag.

Example:

1. Do one thing:

# Bad: Function doing multiple things
def process_data_and_send_email(data):
    process_data(data)
    send_email(data)        

# Good: Separate functions for each task 
def process_data(data):
      # Process data logic 

def send_email(data):
      # Send email logic        

2. Use descriptive names:

# Bad: Unclear variable names 
def func(x):
     return x * 2        

# Good: Descriptive variable names 
def double_number(number):
      return number * 2        

3. Prefer fewer arguments:

# Bad: Function with many arguments 
def calculate_price(quantity, price_per_unit, tax_rate, discount):
      return quantity  price_per_unit  (1 + tax_rate) - discount        

# Good: Reduced arguments using a data structure
def calculate_price(order):
    return order['quantity']  order['price_per_unit']  (1 + order['tax_rate']) - order['discount']        

4. Don't use flag arguments:

# Bad: Function with flag argument 
def process_data(data, debug=False):
        # Process data logic 
        if debug: 
               print("Data processed successfully!")