building site

JavaScript Frameworks such as VueJs, React and Angular, have considerably helped Junior developers in getting up to speed within the Front End industry. Unfortunately, this “easy of learn” has also resulted into a multitude of “bad practices” and “lack of development principles”, as covered in my blog post “Which JavaScript framework should I learn first

I am a strong advocate of Clean Code (if you have not read the book and or articles about it, I suggest you to do so), and I am going to highlight some of the most important JavaScript Fundamental that are at the basic of my development methodology.

Rule 1: Naming convention

As developers it is hard to believe that we actually spent a marginally greater amount of time reading our code that actually typing it, but this statement is statistically right.
Most of our “development” time, is actually spent reading endless lines of “our” code, trying to see what the next steps are, or reading “other people” code, to find bugs or understand where a new feature may fit well.
Time is always against us, and developers are usually of the opinion that writing shorter variable names will make us type faster! Unfortunately, type faster, does not actually mean Develop faster. Reading short or meaningless variables, will require “mental compilation” and consequently make us lose time.
Another wrong assumption, is that our code is actually “faster” if it uses less characters. This may have been true a long time ago, but with today’s tools such as Webpack, Parcel and Rollup, minification of files is a standards process in many workflows. Minification process take care of extra carachters and make our code as small as possible.
We are now going to over a couple of specific examples that will support you in understanding this topic.

Do not use meaningless names

The use of meaningless names, just makes the code harder to read, as developers are forces to “remember” the real variable value and many times, force him/her to have to go back to re-read it to fully understand his meaning.

//BAD
const c = getCart();  
const d = function(a, b){      
  //diff function  
}  
c.forEach( i => {      
  //what is i?  
})
c.i[0].price //what is this again

//GOOD 
const cart = getCart();  
const timeDifference = function(fromDateTime, toDateTime){
  //diff function  
}  
cartItems.forEach( cartItem => {})  
cart.cartItem[0].price 

Short names

Very similarly with meaningless names, there is no reason to actually short names in general. Even if they seem to be very simple to read to you as you type them. They may actually be harder to read by other developers that may have less business knowledge or developers from a where english may not be the main language.

//BAD

 //BAD
const desc = getItemDesc();  
const addr = "1 Road";  
const lvl = 1;  
const exp = 212;

//GOOD
const description = getItemDescription();  
const address = "1 Road";  
const level = 1;  
const experience = 212; 

Rule 2: Small Methods/Functions

As with the above statement, Methods and Functions readability is key for a well written code. A well written code will have a good level of abstruction, that will support the code understanding.
Small methods are not only simple to read, but also help in reducing bugs (as method scope is reduces), and simplify the integration of Unit Test.

Clattered If statements

Conditional statement are in my opinion, the hardest part of development. On one hand, they offer a very simple way to structure your code so that it follows a logical track, on the other, can be very complex to understand and read.
Most of the time, the complexity of reading this statement is due to “business logic” hidden within the conditional logic ( we are going to cover busines logic later in this chapter).
The easier way to support the “reader” while writing conditional statement, is to abstract the logic into small meaningful methods.

 //BAD
if(user && user.init === true && user.lastLogged < lastMonth){    
  //logic here
}

//GOOD
if(isActiveUser(user)){
  //logic here
}
const isActiveUser = (user) => {
  // the method below could be refactored even further    
  return (user && user.init === true && user.lastLogged < lastMonth);  
} 

Avoid long methods

I have read books that solve the problem with “long Methods”, by providing a maximum lines of code that a method can have. I do not think that method should always be smaller than X lines, but on the other hand, prefer to define a method “length”, by its duty.
My rule of thumb is that, if you are able to explain a piece of code with a single sentence, than that should be abstracted into its own function.

 //BAD
const buyItem = async (item) => {    
  if(store[item.id].legth > 0){      
    const balance = await fetch("Get Balance");            
    if(balance < item.price) return "Not Enough Money";
    balance -= item.price;
    await fetch("Update Balance", balance);
    await fetch("buy item", item, user);
  }  
}

//GOOD
const buyItem = async (item) => {
  const itemAvailable = isItemAvailableInStore(item);
  if(!itemAvailable) return "Item Not Available";
  const fundsAvailable = areFundsAvailabel(item.price);
  if(!fundsAvailable) return "Not Enough Funds";
  //abstracting the fetch request will allow us to make the more robust    
  reduceBalance(item.price);    
  initializeBuyingProcess(item);
} 

Be weary of business logic

When developing a specific application, you will surely be aware of the business logic that drives it. Unfortunately, other developers may not have your same understanding, and writing code that “expect” it, can be hard to read.
When business logic need to be part of your code, make sure to abstract it, to provide enough guidance and information to the reader, so that he will be able to either understand the reasoning behind a code, or be able to gain enough information to be able to ask around.

Note I am not using comments. I personally believe that if you need a comment, than it means that the methods and code is not readable enough.

 //BAD
const calculateAPR = async () => {        
  const apr = 3;        
  if(user.createdAt > "5 years ago"){      
    apr = 2.4;    
  } else if(user.mortgage > 100000 && user.income > 45000){      
    apr = 2.6    
  }
    
  return apr;  
}

//GOOD
const calculateAPR = async () => {        
  const apr = BASE_APR;        
  if(usPlatinumMember(user)){      
    apr = 2.4;    
  } else if(isLowRiskMember(user)){      
    apr = 2.6    
  }
  return apr;  
} 

Rule 3: Simples is better than Cool

I have been a Junior developer as well, and as everyone during their career, I always wanted to show off my latest skills. As my experience increases, and I mature, I started to realise that what really matter is not writing cool code, that achieve everything in a single line, but it is providing simple and readable code that any developers can read and understand.

//BAD
const randomFact = (randomVariable > X) ? (anotherFactIsSet) ? "What" : "Why" : "I am lost";

//GOOD
//the following method is for illustration purpose only. It should be cleaned up furhter following the methods mentioned in this chapter.  
if(anotherFactIsSet && randomVariable > X) {    
  return "What";  
} else if(randomVariable > X){    
  return "why";  
} else {    
  return "I am lost";  
} 

Rule 4: Consistancy

Writing code, is like writing a book. Everyone has a different writing method, and we all like to leave our “signature”, by writing code that we are familiar with.
When working in a team, code consitancy is key, and it is more important that write something that you are happy with. The Javascript ecosystem provides us many tools that help us “format” and “standadize” our code (eslint, prettier).
There is no right or wrong when choosing a development methodology, what matter is all team is on board with it, and that all tools are configured correctly.
A few example on this topic cold be:

  • Quotes (single or double)
  • Tabs / Spaces
  • Function declarations (function method() vs method = function() )
  • Trailing commas
  • Spaces between methods and parenthesis

Rule 5: Buld complexity up

In this last rule, I want to spend a couple of lines on a writing technique, that has always received great feedback.
No matter how big or small a file is, I always make sure it is written using the “newspaper code structure”.


Your code should read like a newspaper article. Important stuff at the top, details at the bottom. 

https://kentcdodds.com/blog/newspaper-code-structure

Most of the examples that we have covered in this chapter, have hinted at this structure. The aim, is to make public methods, easy to read, and increase complexity as the user dive into the code. If this methodology is adopted correctly, your code will include very small and readable public methods with little or not visible logic within them, as shown by the example below.

 //GOOD
const veryComplexMethod(){
  checkBasicDetails();    
  initializeStore();    
  subscribeToPushNotifications();    
  sendWelcomeEmail();    
  NotifyUser();  
} 

Conclusion

JavaScript is a fantastic language, as it offer great flexibility. I always try to emphasise on the importance of good reliable and consistent code. My aim when writing code, is always to make it easy to read, and allow everyone, no matter his/her experience to understand it.

These 5 Rules that form my JavaScript Fundamental, should support you in achieving just that. It take practice and self control (as we are usually always in a rush with tight deadline), but a small investment while writing, will produce amazing results later.