Styling WORST Practices

Metadata

This article is written on 11/8/2023. It has been last updated on 18/2/2024.

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.

Glossary

Overview
Disclaimer
Underestimating the need for clean code.
Spacing and indenting the bad way.
Aligning equal signs.
Not declaring services and variables at the start of the script.
Naming variables badly, part 1
Naming variables badly, part 2
Naming variables badly, part 3
Writing too much code.
Abusing or avoiding comments.
Not already using a style guide.
Not being consistent.
Closure

Overview

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.

Disclaimer

Many of these pointers were extracted from evaera's own style guide that she wrote on GitHub. I strongly suggest reading them too if you are experienced. While I could write my own, the reason why I chose to follow hers instead is simple:

Every style guide may be different - this may lead to inconsistency in styling between scripters. Deviating from an already existing style to publish as my own will only worsen the problem. This problem is exacerbated if you are working with teams.

1) Underestimating the need for clean code.

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.

2) Spacing and indenting the bad way.

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 discernible 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))

3) Aligning equal signs.

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 would you do this?

4) Not declaring services and variables at the start of the script.

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 local works. 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.

5) Naming variables badly, part 1

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.

Don't worry about the length of the variable name either, variable names do not affect memory usage or execution speed.

Below are some general conventions to get you started:

Avoid abbreviations - be descriptive.

eg: players instead of plrs.

Name booleans as though they were yes/no questions.

eg: isCalled instead of called.

Name functions using verbs.

eg: add() instead of plusNumbers().

Be positive with naming.

eg: frozen instead of cannotMove.

6) Naming variables badly, part 2

When it comes to naming variables, functions, and the like, it also helps to follow a general naming convention, like the one below:

Variables are generally named in camelCase.

eg: isEnabled, userXp

Constants (variables that should not change in run-time) are generally named in LOUD-SNAKE-CASE.

eg: HEALTH_REGEN, DATASTORESERVICE

Functions are generally named in camelCase.

eg: addNumbers(), loadPlayerData()

Services are generally named in PascalCase.

eg: DataStoreService, PhysicsService, UserInputService

Methods (not functions) are also generally named in PascalCase.

eg: :GetAsync(), :GetPartsInPart()

Similarly, classes and datatypes, and their properties, are generally also named in PascalCase.

eg: NumberSequence, Vector3.Magnitude

Class constructors are generally named in camelCase.

eg: .new(), .fromRGB(), .lookAt()

Asynchronous function and method names are generally appended with Async.

eg: GetAsync(), GetUserThumbnailAsync()

Private properties (most common in custom classes) are generally prepended with an underscore.

eg: _Events

7) Naming variables badly, part 3

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.

8) Writing too much code.

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:

Use well-supported and reputable public libraries when the need arises. Save your time on problems that don't already have solutions.
Don't declare variables that you will use only once. It's messier, and unnecessarily consumes memory.
Prefer writing generic functions that you can apply for multiple problems.

Code should be boring - aim to do more for less.

9) Abusing or avoiding comments.

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.

10) Not already using a style guide.

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.

11) Not being consistent.

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.

Closure

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.