From 42af517ca9fe8d494fddbf3b37a26132f158c842 Mon Sep 17 00:00:00 2001
From: John Lillis <JohnMichaelFFS@gmail.com>
Date: Sat, 7 Sep 2024 19:47:39 -0400
Subject: [PATCH 1/2] Add resource code guidelines

---
 mtasa-resources/CODING_GUIDELINES.md | 100 +++++++++++++++++++++------
 1 file changed, 80 insertions(+), 20 deletions(-)

diff --git a/mtasa-resources/CODING_GUIDELINES.md b/mtasa-resources/CODING_GUIDELINES.md
index 47a24e1..29ecca8 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,60 @@ 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
+### Avoid anonymous functions
 
-Ensure your code editor (e.g. [Visual Studio Code](https://code.visualstudio.com/) 
-applies the rules established by the project's **.editorconfig** file.
+Rather than using anonymous functions (i.e when calling [`addEventHandler`](https://wiki.multitheftauto.com/wiki/AddEventHandler)), use a named local function instead. For example:
 
-# General principles
+```lua
+-- Rather than this:
+addEventHandler("onPlayerConnect", root, function()
+    outputChatBox("Hello!")
+end)
+
+-- Do this:
+local function onConnect()
+    outputChatBox("Hello!")
+end
+addEventHandler("onPlayerConnect", root, onConnect)
+```
 
--   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.
+### Consistent naming conventions
 
-# Script security
+All function names and variables should use the camel case naming convention. Constant variables should use upper snake case (see below).
 
-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.
+### Use of constants and avoiding [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming))
+
+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.*
 
-# Error handling
 
-TODO
+### Indentation and formatting
+
+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 +120,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.
+
+
 

From 91200e05786704965bb39424a0e6f80b3d8aa0da Mon Sep 17 00:00:00 2001
From: John Lillis <JohnMichaelFFS@gmail.com>
Date: Mon, 16 Sep 2024 10:38:12 -0400
Subject: [PATCH 2/2] Remove anon functions rule

---
 mtasa-resources/CODING_GUIDELINES.md | 17 -----------------
 1 file changed, 17 deletions(-)

diff --git a/mtasa-resources/CODING_GUIDELINES.md b/mtasa-resources/CODING_GUIDELINES.md
index 29ecca8..5cfe585 100644
--- a/mtasa-resources/CODING_GUIDELINES.md
+++ b/mtasa-resources/CODING_GUIDELINES.md
@@ -81,23 +81,6 @@ end
 addEventHandler("onPlayerJoin", root, playerJoin)
 ```
 
-### Avoid anonymous functions
-
-Rather than using anonymous functions (i.e when calling [`addEventHandler`](https://wiki.multitheftauto.com/wiki/AddEventHandler)), use a named local function instead. For example:
-
-```lua
--- Rather than this:
-addEventHandler("onPlayerConnect", root, function()
-    outputChatBox("Hello!")
-end)
-
--- Do this:
-local function onConnect()
-    outputChatBox("Hello!")
-end
-addEventHandler("onPlayerConnect", root, onConnect)
-```
-
 ### Consistent naming conventions
 
 All function names and variables should use the camel case naming convention. Constant variables should use upper snake case (see below).