Coding & Naming conventions

Class and OOP Conventions

IMPORTANT: Lilush follows a specific pattern for defining classes and object-oriented code. This convention must be used consistently throughout the codebase.

• Configuration of a class always lives in self.cfg table

• Everything related to state tracking lives in self.__state table

• Private/internal fields are prefixed with double underscore: self.__private_field

Method Definition: Always use explicit function assignment, never the colon syntax for definitions:

local get_name = function(self)
    return self.__name
end

local set_name = function(self, name)
    self.__name = name
end

Method calls: Method calls use the regular Lua syntactic sugar: my_obj:set_name("Jimmy")

Constructor Pattern: Use a simple new function that returns a table with methods assigned directly (no metatables by default):

local new = function(config, opts)

    local instance = {
        cfg = config,
        -- private fields
        __state = {
            reloads = 0
        },
        __window = {
            size = opts.window_size,
        },    
        __value = opts.value,
        __cache = {},

        -- Methods assigned directly
        get_value = get_value,
        set_value = set_value,
        process = process,
    }

    return instance
end

-- Module export
return {
    new = new,
}

Key Points:

1. No ClassName = {} with __index metatables

2. No function ClassName:method() syntax for definitions

3. Methods are defined as local functions, then assigned in the constructor

4. Helper functions that don't need self remain standalone local functions

5. Module exports only what's needed (OOP modules typically export new; library modules export a table of functions)

Metatables Policy:

• Metatables are allowed when they provide clear value and keep code simpler (for example resource lifecycle hooks like __gc, lazy loading, default lookup behavior).

• For constructor-style OOP modules, avoid metatables by default; prefer explicit methods and plain tables unless a metatable is clearly justified.

• When a metatable is used in project code, keep the usage minimal and intentional.