Organization

Organization is one of the most fundamental aspects in making your code predictable, easy to follow, and clean. Having a consistent structure that your code falls into allows for any reader to easily jump to where they need to be and for an editor to know where their edits should go.

Block Scopes

Block Scopes don't exist in every language; but when they do, they are an unbelievably helpful organization tool. They can be used to encapsulate a large section of code or to isolate a scope so that temporary variables don't persist within a broader scope: but, they should only ever be used for these cases.

Examples:

-- Handle Instance Watching
do
    ...
end

... = () => {
    const filteredElements = []
    {
        const elementPriorities = []
        const elements = []
        for (const [element, priority] of map.entries()) {
            ...
        }

        ...
    } 
}

Structure

This is the required order of sections. Each used section must have a comment denominating its start and a single line of whitespace after its end.

1. Built-In Services/Imports

• If Roblox, the comment has to be "Roblox Services".
• Otherwise, "Built-In" and then suffixing whatever is contextually appropriate.

-- Roblox Services
local Shared = game:GetService("ReplicatedStorage")

2. Developer Made Services

• If Roblox, the comment has to be "Game Services".
• Otherwise, "Services" and then prefixing whatever is contextually appropriate (if anything).

-- Game Services
local PlayerProfiles = require(Server.Services.PlayerProfiles)

3. Packages

• This typically includes universally shared modules of utility/low-level code; in the Roblox context this would be utility/low-level modules shared between Games, in any other typical context this would be "packages" from a Package Manager.
• The comment has to always be "Packages".

-- Packages
local Maid = require(Shared.Packages.Maid)

4. Modules

• This is a group of categoric sections that each contain modules respective to their category.
• The layout order for the Module sections has to be done in relation to the codes context. So Module sections that are more foundational/componetized would be closer to the top and those more related to the code itself would be closer to the bottom.
• The comment always has to end with "Modules" and can be prefixed with anything that accurately describes the category of the modules which reside within the respective section.

-- System Modules
...

-- Universal Modules
...

-- Related To Code Modules
...

5. Code

• This is what primarily defines where actual code resides.
• If defining an Interface/Module, the comment should be "Module"

-- Module
local Module = {}
...

• If defining a Service, the comment should be "Service"

-- Service
local Service = {}
...

• If defining a Class the comment should be "Class"

-- Class
local Class = {}

-- Constructor
function Class.new()
    ...
end

...

• Otherwise, the comment can simply state whatever is necessary and appropriate for the context.

-- Handle watching
local collectedElements = {}
do
   ...
end

-- ...
...

6. Return Statement

• The comment here should simply reflect the comment seen in part "#5. Code" placed right before the return statement.