Architecture & Design

Best Code Practices for Writing Clean Code

Each line of the code that makes a program complete should be readable, maintainable, efficient, and secure. Good code is always written by considering that other programmers are also going to work on it. Writing such code requires a programmer to follow certain coding guidelines.

Most of the programming languages have their coding standards and tools to evaluate them, but many guidelines are outside of these language barriers. They look a bit time-consuming and complicated when you follow them the first time, but with the time spent on them, you will start to see more benefits out of them.

 

Naming Conventions

All variables, functions, classes, namespaces, and packages should use meaningful, consistent, and clear naming conventions. Using a consistent naming convention across the code-base will make the code very elegant, readable, and understandable to the others. 

One should never hesitate to use long names for a variable as long as they meet the scope in the code. You can use I, J, or K for variable names if the scope of the variable remains within 2-3 lines of the code. If a variable is used at multiple places (a large scope) then you can go for long descriptive names.

Function and Class names should be expressive enough to say what they do.

function add_numbers(num_a, num_b){
    # add numbers here
}

function concat_strings(str_a, str_b){
    # concating string here
}

 

Avoid Negative Conditions

Negative expressions are always complicated to understand so they should be avoided. 

The conditional expression should always be expressed as positives.

if not is_not_allowed(){
    # bad conditional expression
}

if is_allowed(){
   # preferred way
}

Naming for the boolean type variable should also use the same approach.

 

Function and Class Designs

A function should be defined to take fewer arguments as more arguments add more complications. Having 1 argument is always desired, if not possible then there should be 2 arguments, and if still, it is not possible then 3 or 4 arguments max.

There should be only one entry and one exit in a function. There should only be one return statement in a function as more than 1 return from a function increases the complexity.

A function/Class should be defined to do one thing, it should never do more than one thing. They should be designed and defined by strictly following SOLID principles.

 

Error Handling - try/catch Blocks

Good code is always supposed to have logic to catch and handle unknown exceptions. Most of the programming languages (almost) come with preloaded libraries to support try/catch blocking. Every function of a program should have its own try/catch block. This means if multiple functions are being invoked from a common-place then try/catch block should not be placed in that common-place, instead, each function should have its exception handling block.

function common_function(){
    function_a();
    function_b();
    ....
    ....
}

function function_a(){
    try{
         # code here
    }
    catch{
         # code here
    }
}

function function_b(){
    try{
         # code here
   }
    catch { 
         # code here
    }
}

Any function with try/catch/finally block should always start with a try statement and you should always avoid writing code outside this block.

function function_c(){
    try{
         # code here
   }
    catch{
         # code here
   }
   finally{
        # code here
   }
}

 

DRY Principle

DRY stands for Don’t Repeat Yourself. The same piece of code should not be repeated over and over again. Get rid of redundant code. Placing your business logic into smaller reusable functions will reduce redundant code. It will also make the code more maintainable and reusable.

 

Commenting

Good code doesn't need commenting, but bad code does. Though this is not always true, sometimes complicated business logic makes us leave some hints for the future. Comments should never be too long nor too complicated to understand. Unnecessary long commenting can overkill the intention. 

 

In-built vs Custom Functions

Every programming language comes with in-built functions for data computation and handling data behaviors. Programmers should prefer to use an in-built function rather than reinventing the wheel by writing their own functions. In-built functions are always considered to be more efficient, precise, and time-tested ones.

 

Dead Code

Most of the programmers (especially the new ones) comment out their code while modifying existing code so that they can revert it when things get out of hand. This approach can lead to a huge amount of dead code which can smell awful over time (as no one maintains with new changes). This approach should never be followed as long as code is hosted on remote code repositories, as it can be easily reverted from there. Even if you found some dead-code from the past you should remove it immediately.

 

Architecting Code 

When you get a new requirement to turn into a piece of code, before writing the first line of the code you need to step back and think about:

  • What is it going to do?
  • What is the impact on the existing code?
  • What structure should it have?
  • How to break it into more reusable components
  • How to write it to make it easier to maintainable?

 

Code Refactoring

Refactoring is a process of restructuring your existing code without affecting its behavior and functionality. We always see a change in the technologies over time and you will want to adopt those changes in your programs. Some of the approaches which you applied in the past might be outdated now or maybe you did that because you were not aware of a better solution at that time. This is a very normal thing, every programmer gets better with time and you should never shy away from refactoring outdated and problematic codes. Refactoring should be performed more frequently to avoid too much technical debt.

 

Code Reviews and Pair Programming

Every code change performed by a programmer must be reviewed by someone else and that should also be communicated to other team members. Most of the programmers think that code review is performed to ensure the readability of the code, but it should cover almost every point mentioned in this article. Not every task requires the effort of two programmers, but still, pair programming should be done wherever possible.

 

Unit Tests and Test Coverage

Most programmers don't want to write unit tests as they find them boring and time-consuming, but one should always plan to write efficient test cases that should cover every edge-case scenario that could break. Test coverage tools play significant roles in creating test strategy. They help to find out the most insufficient part of the code (functions, classes, and packages) to be tested.

Share post

  •  
  •  
  •  
  •  

Tilak S.

Technology freak, Open Source lover. Someone trying to understand many things. Wants to make a difference. Life liver and Peripatetic.

Other posts you might like