Writing code isn't just about making it work; it’s about making it clean, easy to read, and maintainable in the long term. This is something every programmer should learn and adhere to.

Writing clean and sustainable code doesn't only mean ensuring it meets the requirements and performs its tasks correctly. It also means making the code understandable so that future modifications, fixes, or expansions can be done without adding complexity or introducing errors from working with previous code.

Why Clean Code Matters

Writing clean code is about creating code that not only meets the expectations for functionality right now but also takes future use into consideration. This is especially important when a project expands or when others need to collaborate with you. Clean and easy-to-understand code ensures that future improvements or bug fixes can be done quickly and without complications.

If our code is complex or hard to understand, future development will become more difficult and time-consuming. Unexpected errors may arise, or adding new features may become hard or even impossible. Additionally, fixing bugs will take longer because it requires understanding the previous code, which might be convoluted or unclear, thus slowing down the development process.

Writing clean code also facilitates smoother teamwork. When developers can easily read and understand each other's code, communication within the team becomes easier. This helps in troubleshooting and improving code more effectively.

Furthermore, when we write clean and understandable code, we reduce the risk of bugs or problems that might not be apparent at first but could emerge later during development or when the system is in use. Writing clean code is an investment in the quality of the work and the long-term performance of the system.

1. Use Meaningful Names

One of the most important principles of writing clean code is using meaningful names that are easy to understand. Naming variables, functions, or classes should be clear and reflect their role or function, which helps anyone reading the code (whether it's you or someone else on the team) to quickly understand what it does.

Example: If you're creating a function to calculate the price of a product, a function named calculate() might not be clear enough about "what is being calculated?" Therefore, naming the function calculatePrice() or calculateTotalPrice() makes it clear that the function is responsible for calculating the price or the total price.

Tips

• Use names that describe what the variable or function does or holds, like userName instead of name , or getTotalAmount() instead of calculate().
• Avoid using vague or non-descriptive names like data , info , or temp , as they don’t indicate the actual purpose.
• If a function does too many things, consider breaking it down into smaller functions for easier understanding and testing.

Using meaningful names not only makes your code cleaner and easier to read but also helps with maintenance in the future without needing additional explanations.

2. Make Functions Short and Concise

Writing short and concise functions is another essential principle of Clean Code. Functions that are too long not only make it harder to read and understand but also affect future maintenance. When a function has too many responsibilities, it can lead to unexpected errors, and it becomes difficult to test and update the code in the future.

Principles to Follow

• A function should do only one thing: A good function has a single responsibility and does it well. For example, if you need a function to calculate tax, you should create a calculateTax() function rather than having it calculate both tax and deduct exemptions in one function.
• Reduce complexity: If a function has many lines, check if it’s doing multiple tasks at once. If so, break it down into smaller functions, so each function can perform a single task simply and effectively.
• Use simple commands: Don’t make a function too long or complicated. Use straightforward and clear commands.

Example: Suppose you need to create a function that calculates the price of a product after applying a discount. Making the function handle multiple steps in one go can lead to long and hard-to-understand code. Therefore, breaking the function into smaller ones makes it easier to read.

python

# Function that does multiple things
def calculatePrice(item):
  discount = item['price'] * 0.1
  price_after_discount = item['price'] - discount
  tax = price_after_discount * 0.07
  total_price = price_after_discount + tax
  return total_price
  
# Function broken down into smaller, understandable pieces
def calculateDiscount(price):
  return price * 0.1
  
def calculateTax(price):
  return price * 0.07
  
def calculatePrice(item):
  discount = calculateDiscount(item['price'])
  price_after_discount = item['price'] - discount
  tax = calculateTax(price_after_discount)
  total_price = price_after_discount + tax
  return total_price

Making your functions short and concise not only helps make your code easier to read but also enables programmers to maintain and expand the code more easily in the future, reducing errors that may arise from modifying long and complex code.

3. Avoid Code Duplication

Code duplication is one of the practices you should avoid when writing Clean Code. If you find that the same code is written multiple times across different parts of your program, it makes the code harder to maintain and can easily lead to errors when the code is modified or updated in the future.

Avoiding duplication helps clean up your code and makes it easier to work with. You don't have to waste time modifying multiple parts of the code; if you change or update a function, it will automatically affect all other parts of the project that use that function.

Principles to Follow

• Extract duplicate code into functions or classes: If you find that the same calculation or process is repeated in multiple places, you should extract that code into a function or class that performs the same task in a clear way.
• Use tools: Tools like Integrated Development Environments (IDEs) or search tools can help you quickly find duplicate sections of code.

Example: Let’s say we have code that calculates discounts and taxes in multiple places across the project, leading to duplication. Leaving this code as is would make it difficult to update and maintain in the long run.

Code with Duplication:

python

# Calculate discount
discount1 = price * 0.1
# Calculate tax
tax1 = price * 0.07

# Duplicate code elsewhere
discount2 = price2 * 0.1
tax2 = price2 * 0.07

Avoiding Duplication:

python

def calculate_discount(price):
  return price * 0.1
  
def calculate_tax(price):
  return price * 0.07
  
# Use functions to handle duplicate calculations
discount1 = calculate_discount(price)
tax1 = calculate_tax(price)

discount2 = calculate_discount(price2)
tax2 = calculate_tax(price2)

By avoiding duplication, you reduce complexity and make it easier for programmers to maintain the code in the future. If you need to change a calculation in a function, you don’t have to modify the code in multiple places across the project—just update the function, and everything will be automatically updated.

4. Using Clear Comments

Commenting your code is an essential tool that helps others (or even your future self) understand the purpose and meaning of the code more easily. However, comments should not make the code messy or reduce its clarity. Comments should only be used when necessary, such as when the code is complex or uses uncommon techniques. This helps others understand how the code works and why a particular technique was used.

Principles to Follow:

• Comment when the code is hard to understand: If you're writing code that might confuse others (or even yourself in the future), add clear comments explaining how the code works.
• Explain why rather than what the code does: Comments should explain "why" and "why this approach" instead of just explaining "what" the code does. Reading a comment that simply states what the code is doing may not help understand the rationale behind the code.
• Avoid unnecessary comments: If the code is already easy to understand, avoid excessive commenting. Too many comments can make the code cluttered and hinder readability.

Example:

Code without comments:

python

def calculate_area(radius):
  return 3.14 * radius * radius

Code with comments:

python

def calculate_area(radius):
  # Using the approximation of π (3.14) to calculate the area of a circle
  return 3.14 * radius * radius

In this case, the code is fairly easy to understand, but the comment explaining that we are using the approximate value of π is important because someone might modify the code in the future and may not know that 3.14 is an approximation of π.

Appropriate example of using comments:

python

def parse_data(data):
  # Check if data is a dictionary (JSON format)
  if not isinstance(data, dict):
      raise ValueError("Input data must be a dictionary")
  return data

Here, the comment helps explain why we need to check the data type before proceeding with the function. Without this check, data that does not match the expected type could cause errors during processing.

Using clear and meaningful comments can greatly improve the readability and maintainability of your code, ensuring that future developers (or even you) can quickly understand the logic behind the code without unnecessary confusion.

5. Test the Code Regularly

Testing code is a step that should not be overlooked. It not only ensures that the code works as expected now but also verifies that when code is modified or improved in the future, the system still works correctly as intended.

Testing helps prevent errors that might affect other functions running in the system and ensures that the code you write will continue to function as defined, even after development and improvements in the future.

Principles to Follow

• Write tests for every function: Every function you write should have a clear test, especially functions with logic or calculations that are crucial.
• Automated Testing: Using tools like JUnit or PyTest for automated testing ensures that you can test your code every time there is a change, guaranteeing that no errors are introduced.
• Test Edge Cases: Don't forget to test your code for unexpected cases, such as unusual or invalid inputs. This will help make your code more robust.

Example:

python

def add_numbers(a, b):
  return a + b
  
# Test function for adding two numbers
def test_add_numbers():
  assert add_numbers(3, 5) == 8
  assert add_numbers(-1, 1) == 0
  assert add_numbers(0, 0) == 0
  print("All tests passed!")
  
# Run the test function
test_add_numbers()

In this example, the add_numbers() function is tested in several cases, such as adding positive numbers, negative numbers, and zero. This ensures that the code we write works correctly in all scenarios.

6. Make the Code Easy to Extend (Extensibility)

Writing code that can easily be extended or have new features added over time is essential for long-term development. As projects evolve, the code you write may need to be developed, improved, or updated with new features. Therefore, making your code extendable without making it overly complicated is crucial.

The principle of easy extensibility is about writing code that is not cluttered and allows flexibility for adding new functionality without repeating code or modifying the existing code too much.

Ways to Make Code Easily Extendable

• Follow SOLID Principles: Applying SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) helps ensure your code is flexible and can easily be extended.
• Separate Different Functions: If a function is doing too many things, breaking it into smaller, single-responsibility functions will make it easier to extend in the future.
• Use OOP (Object-Oriented Programming): Object-oriented principles allow you to easily extend your code in the future, as you can create new classes that inherit properties from existing classes.
• Avoid Hardcoding: Writing inflexible code that hardcodes values makes future extension and improvements difficult. Using variables that can be re-assigned will make the code easier to extend.

Example of Using OOP for Code Extensibility:

python

# Base class
class Animal:
   def make_sound(self):
       raise NotImplementedError("Subclass must implement abstract method")
      
# Inherited classes
class Dog(Animal):
   def make_sound(self):
       return "Woof!"
      
class Cat(Animal):
   def make_sound(self):
       return "Meow!"
      
# Easy to extend code
animals = [Dog(), Cat()]

for animal in animals:
   print(animal.make_sound())

In this example, the code is easier to extend because we can add new classes that inherit from Animal without changing the existing code. This makes the code flexible and allows for the addition of new features with minimal changes.

Summary

Writing Clean Code means creating code that is not only functional but also easy to understand and maintain for yourself and other developers in the future. By using meaningful names, keeping functions short and concise, and avoiding duplication, you can create code that works well and supports the growth and development of your project in the long term.

Learning and adhering to Clean Code principles will help you become a better programmer and enable you to develop high-quality applications in every project you undertake.

🔵 Facebook: Superdev School  (Superdev)

📸 Instagram: superdevschool

🎬 TikTok: superdevschool

🌐 Website: www.superdev.school