This article is written on 11/8/2023. It has been last updated on 18/8/2023.
Contents have been vetted to be accurate up till the date of the update as mentioned above.
This guide was written for all skill levels. For a summary, see the bolded text for each section. For feedback, feel free to post it in the comments below.
Have a look at the code below, and time yourself to see how fast you can figure out what this script does:
local c = Color3.new(1,1,1) local ca = false local cb = Color3.new(0,0,0) local p = workspace.Door local t1 = 1 local t2 = 0 local function f() p.Sound:Play() if not ca then -- bool variable check ca = true -- set bool variable to true p.CanCollide = true p.Transparency = t1 p.Color = cb -- set color else ca = false -- set bool variable to false p.CanCollide = true p.Transparency = t2 p.Color = c end end p.ClickDetector.MouseClick:Connect(f) -- connect function
While this script does work, it undoubtedly took you much longer than expected to understand what the code does, simply because of bad code hygiene.
Good code is not just code that runs quickly and smoothly - it should also be legible and easily understood by scripters, including yourself. This applies especially if you are working with a team of scripters.
This guide will show you the worst things you can do to style your code, and the solutions to avoid them.
Code in your games may be reviewed or rewritten as those games mature; due to how human memory works, you certainly will have to re-read some parts of your code to understand what they do and make changes. Imagine having to change the script I showed above, and the amount of time and effort you would have saved had you just wrote your scripts cleanly from the start!
Writing clean code is a habit you build up over time, and it makes debugging/development that much faster, for you and other scripters that may come to work at your code.
Start writing clean code now, and eventually you will be writing clean code without you even realizing it. Your future self will thank you dearly for it.
Indenting refers to leaving empty spaces just before a line in your code:
if 1 == 1 then print("yes!") -- the space in front of this statement is called an indent. end
For legibility, you should indent your code such that blocks of code within your scripts can be dissected and understood immediately just by looking at it.
In the same vein, you should also not leave redundant spaces between your code, and to only do that if it separates your code into blocks.
-- bad code local x = 1 -- you really do not need these spaces. local y = 1 local function Add(a, b) return a + b -- wheres the indent here? end local f = Add(x, y) print(f)
-- good code local x = 1 local y = 1 local function Add(a, b) return a + b end print(Add(x, y))
Development speed is another concern when it comes to writing code, so do not try to align all the equal signs on your script. You're just wasting time doing so.
local thisIsAVar = "lord," local another = "why-" local third = "even do this?"
You are not improving readability in a significant way, and this is not how Studio and the majority of scripters would format their code anyways. So why even bother?
Not only is declaring services and variables at the start of every script prettier to look at, it is also outright necessary due to how
Always make it a habit to declare your local variables and functions at the beginning of the script.
Doing that also allows you to find your variables in the script faster, since then you will know exactly where to look.
There are many ways to name variables, but as a rule of thumb you should always name variables such that you can almost immediately understand their type and purpose.
Below are some general conventions to get you started:
When it comes to naming variables, functions, and the like, it also helps to follow a general naming convention. The easiest way to abide by this is by following Roblox's.
BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT. BE CONSISTENT.
Don't repeat yourself, and write as little code as possible. After all, the less code you write, the less bugs you get, and the less things to change later.
As a rule of thumb:
Code should be boring - aim to do more for less.
Humans are fallible, so don't shy away from adding comments where needed to tell others and future you what a certain part of your code does. Comments should also answer "why", not "what".
In the same vein, avoid adding so many comments that your scripts look messy. Leave comments out for parts of your script that may be obvious to any scripter.
Optimize code for reading, rather than writing.
This applies tenfold to teams of scripters, where individual scripting styles may differ between scripters.
It helps for team members to follow a style guide, as it lets you understand the code written by each other easily.
Code should not be surprising.
This is just in case point 7 has not driven the point home already.
You may deviate from a style guide or convention as times and circumstances change (and that's fine), just be consistent.
Habit is a powerful force - turn it into your strength.
With what we have learnt in mind, let's change the script that was written in the beginning:
local door = workspace.Door local isDoorToggled = false door.ClickDetector.MouseClick:Connect(function() door.Sound:Play() if isDoorToggled == false then isDoorToggled = true door.CanCollide = false door.Transparency = 1 door.Color = Color3.new(0,0,0) else isDoorToggled = false door.CanCollide = true door.Transparency = 0 door.Color = Color3.new(1,1,1) end end)
That looks like a prettier and easier script to work on, does it not? Or if you like it even shorter, if that fits your taste:
local door = workspace.Door local isDoorToggled = false door.ClickDetector.MouseClick:Connect(function() isDoorToggled = not isDoorToggled door.Sound:Play() door.CanCollide = not isDoorTriggered door.Transparency = if isDoorToggled == true then 1 else 0 door.Color = if isDoorToggled == true then Color3.new(0,0,0) else Color3.new(1,1,1) end)
Writing clean code is a habit that takes time to build - keep writing code, be consistent with your styling, and eventually it becomes muscle memory. When that happens, your future self will thank you for it.
Thank you for reading!