As of 2019-06-15T04:00:00Z, I am a total newcomer to Lua. For this question, I will be demonstrating with general, simple, code from Python.
I usually organize code like this:
# Variables
number=1
# All variables (strings, numbers) go here and are mentioned in functions.
# Functions
def hi():
print(number)
# Code
hi()
# To keep as short and neat as possible, this is meant to call functions and variables.
Is this way of organizing good for Lua too?
The way I organize my code is different(in Lua), take inspiration:
--[[
SCRIPT DESCRIPTION
]]
-- /// -- /// -- /// -- [ ASSERTION ] -- \\\ -- \\\ - \\\ --
warn(script.Name .. ": Operational") -- checks
-- /// -- /// -- /// -- [ SETTINGS ] -- \\\ -- \\\ - \\\ --
-- require a module with settings if there are
-- /// -- /// -- /// -- [ SERVICES ] -- \\\ -- \\\ - \\\ --
-- Players, Lighting, Workspace etc.
-- /// -- /// -- /// -- [ CLASSES ] -- \\\ -- \\\ - \\\ --
-- OOP stuff
-- /// -- /// -- /// -- [ MODULES ] -- \\\ -- \\\ - \\\ --
-- requiring modules if you are working with modular system
-- /// -- /// -- /// -- [ SETUP ] -- \\\ -- \\\ - \\\ --
-- module exclusive
-- /// -- /// -- /// -- [ REMOTES ] -- \\\ -- \\\ - \\\ --
-- organizing remotes
-- /// -- /// -- /// -- [ MODULE VARIABLES ] -- \\\ -- \\\ - \\\ --
-- accessible variables from other scripts if this is a module
-- /// -- /// -- /// -- [ LOCAL VARIABLES ] -- \\\ -- \\\ - \\\ --
-- inaccessible variables
-- /// -- /// -- /// -- [ INITIALIZE ] -- \\\ -- \\\ - \\\ --
-- values setup before on loop
-- /// -- /// -- /// -- [ LOCAL FUNCTIONS ] -- \\\ -- \\\ - \\\ --
-- limited functions
-- /// -- /// -- /// -- [ FUNCTIONS ] -- \\\ -- \\\ - \\\ --
-- accessible functions from other scripts if this is a module
-- /// -- /// -- /// -- [ HOOKS ] -- \\\ -- \\\ - \\\ --
-- connects to event
-- /// -- /// -- /// -- [ MAIN ] -- \\\ -- \\\ - \\\ --
-- here's the working part
Additional organization includes global variables(which I forgot).
It really depends on what you like. I have a pretty good memory and I’m good at instantly knowing where something is so my code is a little messy at times.
On the other hand, if I’m working with a team. I keep my code really clean and comprehensive. It doesn’t really matter how you do it as long as you know the rest of your team can read it with ease.
My layout is usually as follows:
-- Variables at the top
-- Utility functions (Functions that are meant to be used everywhere and aren't specific to one area)
-- Functions
-- Player handles (Such as leave and added)
-- Encryption module connections and Remotes
-- Developer product handle
-- Loops
…do you actually throw a mass of comments like this in your code? I don’t mean to harp on you for something that works for you, but to me this looks relatively messy. I know for me it’d become pretty hard to keep track of things after a while. I don’t want a bunch of green staring me down.
I typically switch coding styles, documentation, conventions and such relatively frequently to see what I like working with. As of right now, I have a simple layout with all names in PascalCase.
-- Documentation:
--@ ScriptName
--@ colbert2677
--# Summary of code
-- Order of code (typically):
-- - Services
-- - Constants
-- - Functions
-- - Implicitly-ran code (hooking functions, running chunks, etc)
The main point of code organisation is readability. In some cases, the order of variables has an impact on the functionality of your code as well. Everyone has a different code organisation style, there isn’t quite a single answer to apply to this question.
Someone wrote a style guide that describes the Roblox variant of writing code in Lua. This is just what Roblox does though and you don’t necessarily need to adhere to it - again, whatever works for you and your collaborators is good enough.
You can check out the style guide here:
https://github.com/vocksel/roblox-style-guide/blob/master/README.md
This hurts my eyes. Decorating your comments with brackets and slashes takes up a ton of unnecessary space and I personally don’t think it looks good, although others might disagree.
You can also check out the roblox lua styleguide that they use internally : Roblox Lua Style guide
Alright, let’s see if I can create another script template with organization to minimize headaches and create it in correct method.
You don’t have to, nor is there a “correct” way of writing your code. I just personally think that, even though this may work for you, it may give potential collaborators a headache as well as yourself in the future. Making your documentation fancy like this is pretty and all but it hurts readability.
Code organisation is really up to the person writing and maintaining the code (i.e. you), as they are the one who will be reading it the most.
That said, there are some conventions which I find help keep code organised
Get Services, require ModuleScripts, and declare constants - in that order - before the rest of your code. This is similar to the Python convention of importing libraries and modules in the first few lines of your program.
Choose a namespace for each type and stick to it. I use snake_case for variables, camelCase for functions and constants.
I use PascalCase for any top-level singletons suchs as services (i.e. local Players = game:GetService("Players")) and ModuleScripts (i.e. PlayerManager = require(script.PlayerManager)),
Split your code into ModuleScripts as well as functions; these can be called similarly to the way you import libraries in Python, and can help with code organisation. How you split your code up however is your choice.
As has been pointed out already, if you’re looking for an equivalent to PEP8 then check out this style guide written by the Roblox team.
Thank you! I feel like this coding style is very useful, and I definitely like it! I have marked this post as the solution and bookmarked it for further reference.
Cheers 
,
Snowman