G2Labs Grzegorz Grzęda

March 17, 2023

As an intermediate programmer, you’ve likely improved your coding skills and have a good understanding of various programming languages. However, writing clean and maintainable code is crucial for enhancing the readability, scalability, and ease of maintenance of your software. In this guide, we’ll explore some best practices and principles for writing clean and maintainable code, along with extensive examples in both C and Python.

1. Naming Conventions

One of the foremost principles of writing clean code is using meaningful and descriptive names for variables, functions, and classes. This enhances the readability and understandability of the code for yourself and others who may work with it in the future.

Example in C:

1
2
3
4
5

// Bad naming
int a;

// Good naming
int totalSales;

Example in Python:

1
2
3
4
5

# Bad naming
x = 5

# Good naming
num_of_students = 20

In the above examples, the use of descriptive names such as totalSales and num_of_students makes it clear what the variables represent, leading to more readable code.

2. Code Structure and Formatting

Consistent code formatting and structure make it easier for others to read and understand your code. Additionally, adhering to a standard format ensures that your code looks clean and professional.

Example in C:

1
2
3
4
5
6
7
8
9

// Bad formatting
int add(int a,int b){
return a+b;
}

// Good formatting
int add(int a, int b) {
    return a + b;
}

Example in Python:

1
2
3
4
5
6
7

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

# Good formatting
def multiply(a, b):
    return a * b

In the above examples, we see that consistent indentation, proper spacing, and formatted code make it much easier to read and understand the functionality.

3. Code Comments

Adding meaningful comments to your code can greatly aid in understanding the logic and purpose of specific sections or functions. However, it’s important to avoid over-commenting and focus on providing insights that are not immediately obvious from the code itself.

Example in C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Bad commenting
// Function to add two numbers
int addition(int x, int y) {
    return x + y;  // Returns the sum
}

// Good commenting
// Function to add two numbers
int addition(int x, int y) {
    return x + y;  // Returns the sum of x and y
}

Example in Python:

1
2
3
4
5
6
7
8
9

# Bad commenting
# function to calculate square
def square(num):
    return num * num  # returns the square

# Good commenting
# function to calculate square
def square(num):
    return num * num  # returns the square of the input number

In these examples, the improved comments provide additional clarity about the purpose and behavior of the code.

4. Modularization and Reusability

Dividing your code into smaller, manageable modules or functions promotes reusability and maintainability. This also enhances the readability as complex logic is abstracted into smaller, understandable components.

Example in C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Bad modularization
int calculate_total_sales(int item_prices[], int num_items) {
    // complex logic for calculating total sales
}

// Good modularization
int calculate_total_sales(int item_prices[], int num_items) {
    return sum(item_prices, num_items);
}

int sum(int arr[], int n) {
    // logic to calculate sum
}

Example in Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Bad modularization
def calculate_total_sales(item_prices, num_items):
    # complex logic for calculating total sales

# Good modularization
def calculate_total_sales(item_prices, num_items):
    return sum(item_prices)

def sum(arr):
    # logic to calculate sum

In the improved examples, the code is broken down into smaller, reusable functions, making it more modular and easier to maintain.

5. Error Handling

Robust error handling is essential for writing maintainable code. Handling edge cases and errors gracefully improves the reliability and maintainability of your codebase.

Example in C:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Bad error handling
int divide(int a, int b) {
    return a / b;
}

// Good error handling
int divide(int a, int b) {
    if (b != 0) {
        return a / b;
    } else {
        // Handle division by zero error
    }
}

Example in Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Bad error handling
def divide(a, b):
    return a / b

# Good error handling
def divide(a, b):
    if b != 0:
        return a / b
    else:
        # Handle division by zero error

In the improved examples, the code checks for potential errors and handles them gracefully, ensuring the stability and maintainability of the code.

These principles and best practices are essential for writing clean and maintainable code. By practicing these concepts and implementing them in your projects, you can greatly improve the readability, scalability, and maintainability of your codebase.

Happy coding!

➡️ TDD rules

⬅️ Solid principles

Go back to Posts.