Enterprise Lua Coding: Rules and Practices


There are a few rules to follow when writing Lua scripts that will result in a scalable, extensible, and readable project.

1. Each function in its own file

Every function should be in its own file, with the file name being the same as the internal function name.

2. Everything is camelcase

All functions and variable names should be in camel case, with the infrequent exception of classes and constants, which should be PascalCase and CONSTANT_CASE respectively, per convention.

3. Use a linter and autoformatter

A linter and autoformatter should both be used, to catch various mistakes like variable shadowing, unintentional globals, unhandled file errors, etc. There are popular Lua extensions for VS Code which give good IDE language support.

4. Use local variables only

Global variables or functions should be avoid, to avoid affecting the global namespace. Instead, you can use higher order function closures and 'require' statements to exclusively use local data when building your script.

5. Throw errors early

Using the 'error' function to throw errors early and often makes your program easier to debug (if using hooks, you may need to use 'xpcall' as well to display the error message). Instead of continuing to run, it's easier to reason about program flow state if non-recoverable constraints are discarded from the flow graph at the earliest point.

6. Add block comments to all module elements

All elements from modules (i.e. functions or variables which are returned) should be documented in the block-style such that the function description shows up in the IDE on-hover. This makes it easier to approach later on what you may have forgotten the context of what you were writing.

7. Use higher-order functional utilities

Encoding and using higher order functional utilties like 'map', 'compose', 'uniq', etc. to avoid verbose for statements should be encouraged, as it makes the code more elegant and easier to read (within reason).

8. Make most functions small

Functions should generally do one thing only, which means they should probably be small. Functions with less than ten statements is ideal, and having more smaller functions is strictly better than having one large hard-to-reason about function.

9. Extract out commonalities in logic

Commonalities in logic or steps to take should be abstracted out into a higher-level abstraction, such that the underlying logic is re-used among call-sites. This makes the code easier to reason about (less to keep track of) and shorter, within reason. As well, it allows future changes to more efficiently affect more parts of the code functionality, such that you don't need to update multiple places in your script.

10. Organize source files into subfolders

Organizing source files into many nested subfolders improves the ontological properties of your codebase, and allows quicker navigation and parsing.