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:
# All variables (strings, numbers) go here and are mentioned in functions.
# To keep as short and neat as possible, this is meant to call functions and variables.
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)
-- Player handles (Such as leave and added)
-- Encryption module connections and Remotes
-- Developer product handle
…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.
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 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.