Scripting: Best Practices – Arma Reforger
Getting started
In the domain of development, any rule is a rule of thumb. If a rule states for example that it is better that a line of code doesn't go over 80 characters, it doesn't mean that any line must not go over 80 characters; sometimes, the situation needs it.
If the code has a good structure, do not change it to enforce a single arbitrary rule. If many of them are not implemented/not respected, changes should be applied; again, this is according to one's judgement.
With that being said, let's go!
Best practices
Code format
- Reminder: chosen indentation for Enfusion is Allman style
- Reminder: indentation is done with tabulations
- Use empty space. Line return, spaces before and after brackets, if this improves readability, use it: space is free
- One-lining (putting everything in one statement) memory improvement is most of the time not worth the headache it gives when trying to read it: don't overuse it
- it also hinders debugger's usage, e.g in the event of an inlined if
Variable format
- Name variables and functions properly: code must be readable by a human being, e.g variables like u instead of uniform should not exist.
- i is an accepted iteration variable name (e.g in for loops).
- Prefix any public content (classes, global methods, global variables) with a Creator Tag in order to prevent conflicts with other mods.
- Use the closest value type whenever possible; using auto for a known variable type makes code less clear.
Code Structuration
SOLID
A series of development principles to follow in order to ensure an easy code maintenance and lifetime.
DRY
Don't Repeat Yourself. If within the same class, the same code or the same pattern is written in various places, write a protected method and use appropriate parameters.
Logical Simplifications
If the code has too many repetitions, make a common method as stated above.
If the code has too many levels, it is time to split it and rethink it.
Examples
| Improvable | Good |
|---|---|
auto number = 42;
Animal cutePet = new Dog();
|
int number = 42;
Dog cutePet = new Dog();
|
for (int i = 0; i < list.Count(); i++)
{
}
|
for (int i = 0, count = list.Count(); i < count; i++) // only one list.Count() call
{
}
|
// declaring 'text' string in every for loop creates a pointer attribution for each loop
for (int i = 0, count = list.Count(); i < count; i++)
{
string text = "Value " + i + " is " + list[i];
Print(text);
}
|
string text; // external declaration = one pointer attribution
for (int i = 0, count = list.Count(); i < count; i++)
{
text = "Value " + i + " is " + list[i];
Print(text);
}
which can also be simplified to foreach (int i, element : list)
{
PrintFormat("Value %1 is %2", i, element);
}
|
if (a)
{
if (b)
{
if (c)
{
Method(true);
}
else
{
Method(false);
}
}
}
|
if (a && b)
{
Method(c);
}
|
Boilerplate code:
int i = 0;
if (a)
{
i++;
}
if (b)
{
i++;
}
if (c)
{
i++;
}
|
Simplified:
int i = 0;
array<bool> conditions = { a, b, c };
foreach (bool condition : conditions)
{
if (condition)
{
i++;
}
}
or (if some other code is involved) int i = 0;
IncrementIfTrue(a, i);
IncrementIfTrue(b, i);
IncrementIfTrue(c, i);
void IncrementIfTrue(bool condition, out int value)
{
if (condition)
{
value++;
}
}
|
Initialise(player1, 1);
Initialise(player2, 2);
Initialise(player3, 3);
Initialise(player4, 4);
Initialise(player5, 5);
Initialise(player6, 6);
|
array<IEntity> list = { player1, player2, player3, player4, player5, player6 };
foreach (int i, item : list)
{
Initialise(item, i + 1);
}
|
Code Comments
Code comments are surprisingly not a must-have; code organisation combined to variable names should be enough to be read by a human, then comment can be used:
- a comment should explain why the code is written this way
- a comment should not tell what the code does; code should be self-explanatory
- as a last resort in the event of a complex piece of code, a comment can be used to describe what the code actually does - or at least its intention
- On the other hand, Documentation is more than welcome as it provides information from the outside without having to read the code. Enfusion uses Doxygen format.
Files organisation
- Have one class/enum per file
- Small classes/enums can always be grouped together in the same file, provided they are part of the same system or only used there
- Use (sub-)directories to group related classes