Clean Code

Clean code is a programming style that acknowledges other people that will encounter the source files. Writing clean code is good for the long-term maintenance of a project and reduces confusion when source files are retrieved at a later date. In open-source software projects, writing clean code is almost mandatory because many people from various locations will sift through it when contributing to the project. Clean code makes use of the following:

• Descriptive comments that explain methods clearly.
• Relevant variable names to make the source code simple to work with.
• Refactoring to shorten the length of the file and potentially improve application performance.

In this article, I will make use of JavaScript to demonstrate my idea, but let it be noted that these principles can be applied to any programming language.

Comments In Code

Programmers ought to write comments in their code understanding that fellow programmers may have questions about certain methods within the file. A good practice is to write a paragraph at the top of the file in the block comment form. The section could include the author, the purpose of the program, the date of writing, and any errors that can be encountered. Writing comments is essential when pair programming and contributing to a public code base.

/* 
Author: Buzz Lightyear

Date: 11 January 2023

Aim: The following program includes a class that has several methods for executing space missions

Co-authors: Woody, Sid, & Mr. Potato Head
*/

Good Variable Names

Variables are the core of any program in every programming language. They are usually the first language syntax that someone will see inside a source file and will probably be referenced multiple times throughout the program. Depending on the purpose of the program, it may be necessary to include the data type of the variable, especially in older languages that require a type declaration. It is also important to keep the names short and concise, for example instead of a variable called micropachyCephaloSaurus, we can call it microSaurus and use comments to describe the code. Variable names should be unique and relevant to the use case. I have included some good variable name examples below.

// Bad variable names that are generic

    var name = 'Andrew'; 
    var name2 = 'Garfield';
    var vehicle = 'Boeing 737';
    var list = ['iPhone', 'Galaxy', 'Nexus'];
    
// Good variable names

    var firstName = 'Andrew';
    var lastName = 'Garfield'; 
    var airplane = 'Boeing 737';
    var smartPhones = ['iPhone', 'Galaxy', 'Nexus'];

Code Refactoring

Refactoring is writing code with the length of the file in mind, this includes sifting through previously written source files and applying simpler syntax. This makes the code easy to read especially when combined with good variable naming conventions. Secondly, since the compiler reads the code per line, the less syntax it has to comprehend the faster the program will execute.

Consider this function:

// A function to compute all the elements in an array
function runningTotal(list){
    let total = 0;
    
    for(var a = 0; a < list.length; a++){
        total += list[a];
    }

    return total;
}

runningTotal([1, 2, 3]); // calling the function

The function above uses 6 lines if we exclude calling the function. A good way to refactor a function is to use arrow functions, supported in JavaScript. Arrow functions can cut a large function declaration to a single line. We can re-write the runningTotal function as shown below.

// A function to compute all the elements in an array
    function runningTotal(list){
        return list.reduce((total, currentNum) => total + currentNum); 
}

runningTotal([1, 2, 3]); // calling the function

Some of the advantages of refactoring code are only available in modern programming languages that are dynamically typed such as JavaScript and Python. One other way that I like to refactor code, call it a preference if you will, is to use dot notation instead of bracket notation when calling objects. Consider the code below.

// An object that stores basketball player scoring averages

    let ballPlayerStats = {
        Lebron: 25.0,
        Embiid: 32.0,
        Luka: 31.2,
        Tatum: 30.0,
        Lillard: 27.5
    }

We can reference an object property in one of two ways; dot notation or bracket notation. Bracket notation can become very confusing to read in long source files, I usually reserve brackets and parentheses for functions, loops, classes, etc.

// Can be pretty confusing next to an array
    ballPlayerStats['Luka'];
    
    let vehicles = ['Ford', 'Jeep', 'Chevrolet'];

// More clean and identifiable
    ballPlayerStats.Luka; 

Wrapping Up

In this article, I have explained why clean code is preferable to complex code. I tried to keep this one short and to the point, much like clean code. Writing in this way is completely optional and does not affect the successful execution of a program. Computers understand the code whatever way we write it but unfortunately, we don't write code for them only. With these techniques in mind, you can contribute to public code bases with ease and avoid conflicts with other developers. If you enjoyed this article or would like to share some feedback, reach out to me here.

~ Thank you for reading