Skip to content

Latest commit

 

History

History
133 lines (98 loc) · 4.56 KB

CODING_GUIDELINES.md

File metadata and controls

133 lines (98 loc) · 4.56 KB
Raw

Contents:

Introduction

We appreciate your interest in contributing to the development and improvement of the Default Lua resources that come with the Multi Theft Auto (MTA) multiplayer mod. To ensure high-quality code and a smooth collaboration process, please adhere to the following coding guidelines.

General principles

  • Write clear, readable, and maintainable code.
  • Follow the DRY (Don't Repeat Yourself) principle.
  • Adhere to the KISS (Keep It Simple, Stupid) principle.
  • Use meaningful variable and function names that convey their purpose.
  • Comment your code where necessary to explain the logic.

Code style

Early return

To improve code readability, prefer using early returns to handle error conditions or special cases at the beginning of functions. This helps to avoid deep nesting and makes the main logic easier to follow.

-- Bad example 
function exampleFunction(value) 
    if value > 0 then 
        -- Some logic here 
        if value < 100 then 
            -- More logic here 
            if value ~= 50 then 
                -- Main logic here 
            end 
        end 
    end 
end 

-- Good example 
function exampleFunction(value) 
    if value \<= 0 then return end 
    if value \>= 100 then return end 
    if value == 50 then return end 
    -- Main logic here end 
end

Error handling

Use the Lua error (message [, level]) function to raise warnings when validating parameters passed to a function, with level set to 2 so that the error points the error at the function call location. For example:

-- This function outputs player's name to the chat box
function outputPlayerName(player)
    -- If player is invalid, raise an error
    if not (isElement(player) and getElementType(player) == "player") then
        error("Invalid player!", 2)
    end

    outputChatBox(getPlayerName(player))
end

-- This function is triggered each time a player joins and calls outputPlayerName
local function playerJoin()
    outputPlayerName() -- note the missing player argument; the error will point to this line
end
addEventHandler("onPlayerJoin", root, playerJoin)

Consistent naming conventions

All function names and variables should use the camel case naming convention. Constant variables should use upper snake case (see below).

Use of constants and avoiding magic numbers

Don't use magic numbers in blocks of code - instead, define such values as "constants" at the top of the file using upper snake case.

Note: the version of Lua used by MTA does not support the const keyword added in Lua 5.4. In MTA Lua, the concept of a const is just that - a concept.

Indentation and formatting

Ensure your code editor (e.g. Visual Studio Code applies the rules established by the project's .editorconfig file.

Performance considerations

  • Avoid unnecessary computations within loops.
  • Cache results of expensive operations whenever possible.
  • Use local variables to improve performance.

Don't use OOP functionality

Enabling the OOP functionality in any given resource will incur a performance hit. In general, pull requests to the official resources repository that enable it will generally fail code review.

Use range-based for loops rather than ipairs

Range-based for loops are more performant than loops using ipairs and should be used whenever possible. For example:

-- Rather than this:
for _, player in ipairs(getElementsByType("player")) do
    iprint(player)
end

-- Do this:
local players = getElementsByType("player")
for i = 1, #players do
    iprint(players[player])
end

Script security

Follow the Script security principles established for MTA:SA scripts to ensure the safety and integrity of your code.