Making code a bit more readable

In the past couple of months, I have been making small web apps that don't have super complex code but sometimes there is a lot going on, lots of files, functions variables, etc. I’ve been trying to make my code a bit more clean, to make it easier to explain to others. So I decided to look into some techniques I can use to achieve this!

Sometimes names make a lot of sense to me, but to others….

Naming things…

One of the most difficult things to do when coding is giving things appropriate names. A lot of objects could have the same name but they are still different, so how do you come up with the right (and more specifically, clear) names?

#Tip 1

Use descriptive names, but not too descriptive. getUserData is fague, what data are you getting? getUserPosts is more descriptive, now everyone can see which data I am retrieving with this function (posts!). Don’t go overboard and make this into getUserPostsFromDatabase, from database is unnecessary.

#Tip 2

Stay consistent when naming things. If I use getUserPosts I shouldn’t then use retrieveUsers or returnUsers on other functions, use get.

#Tip 3

Make it known when variables are booleans. var buttonIsClicked or movieHasSubtitles immediately tells me this variable is a boolean.

A good test for boolean variable names is to put the name in an if-then statement and read it outloud. If it reads like a good sentence, you’re in good shape.

For example: if carIsSold or if home.wasSold

Those sound more natural and make the program easier to decipher.

Brandon Wozniewicz, JavaScript naming conventions: do’s and don’ts

You can also follow a specific naming convention to make your code more clear, but these are the basics for making your code more clear in general.

Separating code into modules

For a long time, I have worked with just one javascript file in my projects, the code was usually simple enough to for this to work fine. But once I started working with node and server-side web apps some of the js became difficult to follow (server & client-side). This is when I started learning about modules.

Modules allow for exporting and importing of different javascript files, making it so you can write a piece of code in one file and then use it in another. Using this method code becomes easier to explain because everything has its own place. Also, js files will never be super long either, so it won’t be a mess. A downside to modules is you need to through a bunch of different files to figure out what a specific function does…

A function showing launches, it imports a function from api.js and exports showLaunches to be used elsewhere

An interesting way of organizing code

A few months ago a friend and fellow student shared some of his code using a new way of separating code into modules. It is called the Atomic Design Methodology and it made a lot of people interested in the subject.

Atomic Design is the result of a research into a methodology to craft interface design systems and is based on chemistry. It uses the concept of atoms, molecules, and organisms to group things.

• Atoms are the basic building blocks of all matter. Each chemical element has distinct properties, and they can’t be broken down further without losing their meaning. (Yes, it’s true atoms are composed of even smaller bits like protons, electrons, and neutrons, but atoms are the smallest functional unit.)
• Molecules are groups of two or more atoms held together by chemical bonds. These combinations of atoms take on their own unique properties, and become more tangible and operational than atoms.
• Organisms are assemblies of molecules functioning together as a unit. These relatively complex structures can range from single-celled organisms all the way up to incredibly sophisticated organisms like human beings.

Atoms, molecules, and organisms are used to create the building blocks for the code, with modules being the smallest pieces and organisms being the largest.

• Atoms are like the core elements of a page like buttons, inputs, labels etc.
• Molecules are multiple atoms combined to function as a single unit. For example, a button, input, and label could work together to create a search form
• Organisms are more complex elements made of groups of molecules. For example, the search form from above could be part of a page header. The header is in this case the organism.

Organisms together can form templates and with these templates, you can build web pages! A big advantage of Atomic Design is the reusability of pieces of code. Once you have made an atom, molecule, or organism, that piece or group of code can be used everywhere.

To learn more about Atomic Design in detail, go here: https://atomicdesign.bradfrost.com/chapter-2/

To sum it up…

Naming things consistently and appropriately in my code has been the easiest but also the biggest improvement. It makes things way more clear from the get-go and gives me an easier time explaining things aswell.

I am still getting used to modules but I already feel like my code is more organized and simpler because of it. Code being scattered around takes some time getting used to but I am glad I don’t have one big collection of a bunch of different code in on file.

I have not used Atomic Design yet in my projects but I hope to do so in the near future at least once. I don’t know if it is going to be THE solution for me but it did at least make the use and functionality of modules more clear.

Sources

Atomic Design Methodology | Atomic Design by Brad Frost

JavaScript Naming Conventions - RWieruch

JavaScript naming conventions: do's and don'ts