There are many different ways of writing code that achieve the same goal. However, programmers generally agree that there are some ways of writing code that are more understandable and readable than other ways.
To help write more understandable code, programmers follow a style guide. It provides guidelines for how to write code, how to structure it, common problems to avoid, etc.
Some of the guidelines are so common that there are automatic tools to do it for you! One of these tools is called Prettier. You should have installed this tool when you set up your VS Code extensions.
Prettier is a tool that rearranges your code (called formatting). It follows a set of rules that programmers have agreed make your code easier to read and understand.
You might have a common problem when running Prettier. If you see something like this:
Then you have written some code that is invalid and Prettier can't format it. A common issue is a missing bracket, so try looking for that first.
From when you begin programming it is essential that you follow the guidelines below - a good habit is much easier to get in to when you start!
You may have noticed that programmers tend to indent their code by starting a line of code with some space.
Here's an example in HTML:
Indentation helps us to read our code by visually marking how the code is going to run. Programmers rely on this extra information to quickly read and understand code.
There are some guidelines about where to add indentation. For example, lines of code are indented when they are inside a function, an
if statement or a
for loop. Additionally, if any of those structures are inside another structure, then they are indented further.
The guidelines about where to add indentation can be complex, but the good news is that Prettier adds indentation automatically for us! However it is good to pay attention to where indentation is added, as you may find yourself writing code in an environment where Prettier is not installed.
When you are debugging a problem, you might comment out some sections of your code.
In this example, there is some extra debugging information that is commented out.
Once you have solved the problem, you should remove large sections of commented out code. When you (or someone else) are reading your code, you want to know only the important pieces. Removing commented out code helps find the relevant code faster and easier.
You might be worried about "losing" some experimental code that you want to "save" by commenting it out. However, this can cause confusion about which bits of code still work.
If you want to save some code, remember that you can commit it using Git. It will then be saved it forever. If you decide to remove the code later you can delete it and make another commit. And if you want it back again, you can always look at the deleted code in the git history.
As you write code, you may make changes to the variables that you are using. You may rename some variables, make some new variables or change how the variables are used. This may leave some variables that are unused.
In this example, the
customerName variable isn't used anywhere.
You should remove any variables that are unused. This is because if you (or someone else) is reading your code, it can be confusing if you see a variable and then find out later that it isn't used. It could make you think that there's a bug, because the variable must have been put there for a reason!
Making our code understandable by others is critical to being a programmer. One of the main tools in our toolbox is good naming for our variables and function names.
There are no strict rules to follow when thinking of variable names, but there are some general guidelines.
When thinking about whether a variable name is good, try to imagine that you are reading the code again in the future and you have forgotten exactly how it works.
Do the variable names help explain what the code is supposed to do?
camelCase. This means starting your variable name with a lower case letter, and then every "word" after that starts with an upper case letter.
By doing this it makes it easier to read variable name that have multiple "words".
Very short variable names can be difficult to understand since the purpose of the variable can be unclear. They are also difficult remember, especially if there are many similarly named variables. Try to avoid short names or abbreviations.
Here are some examples of bad names that you should avoid:
- Single letters like
- Abbreviations like
- Generic names like
A good variable name quickly explains what it represents to anyone reading the code. Try to describe what the variable is or what it does within in code.
In this example, the variable name
song doesn't tell us what it is used for. The
isPlaying variable name is better since it tells us whether a song is playing or not.
In this example, the function calculates a percentage and returns it. Therefore it is good to name it using the "get" verb to show that it returns something.
Finally, parameters of functions should also have names that properly represent what is going to be received into the function.
var. The rules on using them at CodeYourFuture are as follows
You should never use
You should use
let for a variable that will change, for example:
For other variables that will never change you should use
const, for example
Sometimes writing long functions are unavoidable, however most of the time is better to split a long function into a few shorter ones.
- Make your code easier to read
- Make your code easier to maintain
- Make your code easier to review by out volunteers
When you writing code you should also try to keep in mind that you will only ever write the code once, but you will read the code many times. Always aim to write code that is readable.
For more details you can read these useful articles
- (The Art of Writing Small and Plain Functions)[https://dmitripavlutin.com/the-art-of-writing-small-and-plain-functions/]
These additional rules may be harder for you to understand at the start of your programming journey however they are important concepts as your develop.
Remember that you are communicating with another programmer!
Don't forget that the person reading your code probably has some understanding of the context. If your function is named
getCustomer, it's probably fine to name variables
age, etc instead of
customerAge. You don't need to explain everything.
Naming variables is more of an art than a science. Often you need some experience reading other people's code before you get really good at it.
When reading other people's code, think about the variable names. If the names are not clear, make sure you understand the code first, then think about what names you would use instead.
Define your variables with the narrowest scope they can have. This is easiest to explain with an example...
It is considered better code to combine the two highlighted lines into one like this...
This is important as when a function (or your code more generally) becomes more complex it will be harder to keep track of what variable is used where.