diff --git a/mtasa-resources/CODING_GUIDELINES.md b/mtasa-resources/CODING_GUIDELINES.md index 47a24e1..5cfe585 100644 --- a/mtasa-resources/CODING_GUIDELINES.md +++ b/mtasa-resources/CODING_GUIDELINES.md @@ -18,6 +18,16 @@ 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](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) + (Don't Repeat Yourself) principle. +- Adhere to the [KISS](https://en.wikipedia.org/wiki/KISS_principle) + (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 @@ -49,37 +59,43 @@ function exampleFunction(value) end ``` -### Consistent naming conventions +### Error handling -TODO +Use the Lua [`error (message [, level])`](https://www.lua.org/manual/5.1/manual.html#pdf-error) 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: -### Use of constants +```lua +-- 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 -TODO +-- 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) +``` -### Indentation and formatting +### Consistent naming conventions -Ensure your code editor (e.g. [Visual Studio Code](https://code.visualstudio.com/) -applies the rules established by the project's **.editorconfig** file. +All function names and variables should use the camel case naming convention. Constant variables should use upper snake case (see below). -# General principles +### Use of constants and avoiding [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) -- Write clear, readable, and maintainable code. -- Follow the [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) - (Don't Repeat Yourself) principle. -- Adhere to the [KISS](https://en.wikipedia.org/wiki/KISS_principle) - (Keep It Simple, Stupid) principle. -- Use meaningful variable and function names that convey their purpose. -- Comment your code where necessary to explain the logic. +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. -# Script security +*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.* -Follow the [Script security](https://wiki.multitheftauto.com/wiki/Script_security) -principles established for MTA:SA scripts to ensure the safety and integrity of your code. -# Error handling +### Indentation and formatting -TODO +Ensure your code editor (e.g. [Visual Studio Code](https://code.visualstudio.com/) +applies the rules established by the project's **.editorconfig** file. # Performance considerations @@ -87,4 +103,31 @@ TODO - Cache results of expensive operations whenever possible. - Use local variables to improve performance. +### Don't use OOP functionality + +Enabling the [OOP](https://wiki.multitheftauto.com/wiki/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`](https://www.lua.org/manual/5.1/manual.html#pdf-ipairs) + +Range-based for loops are more performant than loops using `ipairs` and should be used whenever possible. For example: + +```lua +-- 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](https://wiki.multitheftauto.com/wiki/Script_security) +principles established for MTA:SA scripts to ensure the safety and integrity of your code. + +