diff --git a/mtasa-resources/CODING_GUIDELINES.md b/mtasa-resources/CODING_GUIDELINES.md index 47a24e1..91fb836 100644 --- a/mtasa-resources/CODING_GUIDELINES.md +++ b/mtasa-resources/CODING_GUIDELINES.md @@ -1,90 +1,117 @@ -## Contents: -- [Introduction](#introduction) -- [Code style](#code-style) - - [Early return](#early-return) - - [Consistent naming conventions](#consistent-naming-conventions) - - [Use of constants](#use-of-constants) - - [Indentation and formatting](#indentation-and-formatting) -- [General principles](#general-principles) -- [Script security](#script-security) -- [Error handling](#error-handling) -- [Performance considerations](#performance-considerations) - -# 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**. - -# 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. +## Introduction +Welcome to the coding guidelines for the **[mtasa-resources](https://github.com/multitheftauto/mtasa-resources)** repository!
+We are aware that cooperative work and high-quality code require compliance with the following rules, so we ask all interested parties to take the following into account in all of their contributions. + +## Contents +- [General](#general) + - [Simplicity](#simplicity) + - [Comments](#comments) + - [Returns](#returns) +- [Style](#style) +- [Security](#security) +- [Performance](#performance) + +## General +When you contribute to our codebase, you should always
+Write code that is +- Readable +- Secure +- Scalable +- Maintainable + +### Simplicity +Striving for simplicity is always important, as simple code is easier to read and maintain.
+Some example: ```lua --- 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 +local foo = true + +-- Bad +function bar() + if foo then + return true + else + return false + end end -``` - -### Consistent naming conventions - -TODO - -### Use of constants -TODO - -### Indentation and formatting +-- Good +function baz() + return foo +end +``` -Ensure your code editor (e.g. [Visual Studio Code](https://code.visualstudio.com/) -applies the rules established by the project's **.editorconfig** file. +### Comments +Comments are good - If you use them well!
+Commenting is useful for making complex logic tasks easier to explain, but it's unnecessary to comment every line, like here: -# General principles +```lua +-- Never do this! +-- No one wants to read a comment on every line + +addEvent("foo", true) -- Add the event +addEventHandler("foo", root, -- Add the event handler + function() + bar = 10 -- Set the bar variable to 10 + baz(bar) -- Call the baz function + end +) +``` -- 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. +Instead, use comments to clarify complex logic or provide context where it's needed: -# Script security +```lua +function fiz(x, y) + -- Step 1: Initialize intermediate results + local a = x * y + local b = x + y + + -- Step 2: Perform iterative adjustment on a + for i = 1, 10 do + -- If a is even, halve it; if odd, increment it + if a % 2 == 0 then + a = a / 2 + else + a = a + 1 + end + end + + -- Step 3: Combine results with additional computation + return a + (b * math.sqrt(x^2 + y^2)) +end +``` -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. +### Returns +Early return pattern is preferred, as they provide easier readability and transparency.
+Example: -# Error handling +```lua +-- Nested +function a() + if foo then + if bar then + if baz then + return true + end + end + end +end -TODO +-- Early +function b() + if not (foo and bar and baz) then + return + end -# Performance considerations + return true +end +``` -- Avoid unnecessary computations within loops. -- Cache results of expensive operations whenever possible. -- Use local variables to improve performance. +## Style +To do +## Security +To do +## Performance +To do \ No newline at end of file