What is clean code? Do you need comments to write clean codes?

Subscribe to my newsletter and never miss my upcoming articles

I often get asked these questions by beginners, what is clean code? How to write a clean code? Do you need comments to write clean codes?

So in this article, I will explain what clean codes are, and how you can write one.

To start with, what is clean code? The phrase clean code was from a software engineering principles book titled clean code written by Roberts C Martin,

What is clean code?

In my own definition of clean code, a clean code is an easily readable, self-explanatory, scalable and refactorable code, clean codes are codes that can be easily understood by anyone (even by beginners).

what are the importance of writing a clean code?

There are so many reasons why writing clean codes are important, which includes:

When working with a team:

One of the importance of writing clean codes is to make your codes easily understood by your team who may want to update certain features in a project,or fix bugs at your absence, when your codes are clean , it can easily be updated by anyone even without asking for assistance of what you wrote in your code(s).

Building open source projects:

Making your code as clean as possible will also make it much more comprehensive by open source contributors who would want to contribute to the extensibility and sustainability of your project(s).

When you want to refactor your code:

writing clean codes is not only vital when working with teams, it is also vital for personal reasons, writing clean codes makes updates, and bug fixing a breeze, writing clean codes helps you understand your code after leaving it for months or years, even without any comments in it.

How do you write a clean code?

Now that you know what clean codes are,and their importance, how do you write one? most people think filling up their codes with comments is what makes their code a clean code,

what if I told you that you need little or no comments to write clean codes? yes, you absolutely do not need comments to write clean code(s), you know why? because clean code(s) are self-explanatory, you could point out what they do even in the depth of hundreds/thousands of code lines.

Note: these are just recommendations, not standard coding concepts, not every ideas can be strictly followed.

What are examples of a clean code?

One of the examples of a clean code is the use of self-explanatory variable names, what are self-explanatory variable names? self-explanatory variable names are variable names that spotlights the values they hold, for instance:

let yydd=new Date().getFullYear();

the above variable doesn't explain what it does, anyone coming across the variable name anywhere in your code would have no idea what it does.

but then, how about this?

let fullYear=new Date().getFullYear();

without a second thought, you should already know what values the variable holds, now that's a typical example of a clean code.

Using camelCase variable names and uppercase constant names.

Another typical instance of a clean code is variable structuring, what do I mean by variable structuring? what I meant by this is, having a standard way of declaring your variables, this helps in simplifying your codes readability.

for example:

let dayofmonth=new Date().getDate();

const time=new Date().getTime();

Whenever you or anyone come across these variables in your code, you possibly can't distinguish between the variable and the constant, now this makes understanding your code a tough journey for anyone who tries to read your code.

what if you implement it this way?

let dayOfMonth=new Date().getDate();

const TIME=new Date().getTime();

now this makes it easier to understand and distinguish between a standard letvariable name and a constant constvariable name. also to simplify understanding, you can add a comment at the beginning of your code, for instance:

// standard variables are in camelCase, e.g ourTest;
// while constant variables are in uppercase e.g TEST

let dayOfMonth=new Date().getDate();

const TIME=new Date().getTime();

Don't hardcode Everything.

Hardcoding Everything such as API URLs and API keys could often make your code difficult to refactor, rather than hardcoding them, declare them as a variable and use the variable in place of the URLs/Keys, for instance:

Instead of this,

async function fetchPexelsImages(){
let fetchImages=await fetch('https://api.pexels.com/v1/curated/',{
method:"GET",
headers:{
Authorization:xxxxxxxxxxxxxxxxxxxxxxxxx
}
});

}

you can simply do this,

//declare variables
const PEXELSAPIURL="https://api.pexels.com/v1/curated/";
const PEXELSAPITOKEN="xxxxxxxxxxxxxxxxx";
async function fetchPexelsImages(){
let fetchImages=await fetch(`${PEXELSAPIURL}`,{
method:'GET',
headers:{
Authorization: PEXELSAPITOKEN
}
});
}

With this you can easily change the API URLs or Keys without touching the main code.

Don't overload a Function.

what does it mean to overload a function?(take a guess), well, overloading a function simply means using a single function to perform more than one task, in other to have a clean code, you need to limit your function to one task, this makes your code easily refactorable.

for instance: instead of doing this,

function getUsersInfo(usersInfo){
usersInfo.forEach(userInfo => {
let checkedUserInfo=database.lookup(userInfo);
if(checkedUserInfo.isComplete()){
showUser(userInfo)
}
});
}

you should do this:

function getUsersInfo(usersInfo){
usersInfo.filter(isUserInfoComplete).forEach(showUser);

}
function isUserInfoComplete(userInfo){
let checkedUserInfo=database.lookup(userInfo);
return checkedUserInfo.isComplete();
}

Avoid Unnecessary contexts.

Avoiding unnecessary contexts in your code(s) makes your code a clean code, if the name of your object/class tells you something, then it's not necessary to include them in the variable names. for instance, instead of this:

const PHONE={
phoneMake:"iphone",
phoneModel:"6s",
phoneColor:"gold"
};
function buildPhone(phone){
phone.phoneModel="7plus"
}

you could do this:

const PHONE={
make:"iphone",
model:"6s",
color:"gold"
};
function buildPhone(phone){
phone.model="7plus"
}

I hope you have been able to understand the concepts of a clean code and how to write one, if you would want to read more about clean code, check out Ryan Mcdermott's repo on GitHub.

No Comments Yet