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.

ⓘ

See SOLID.

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.

ⓘ

See Don't repeat yourself.

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();
// a method call is more expensive than a bool check if (obj.MustBeTreated() || m_bTreatAllObjects) Print(obj); if (obj.MustBeTreated() && m_bTreatAllObjects) Print(obj);	// cheap checks go first, expensive checks (method calls) go after if (m_bTreatAllObjects || obj.MustBeTreated()) Print(obj); if (m_bTreatAllObjects && obj.MustBeTreated()) Print(obj);
// many identical method calls if (obj.MustBeTreated() && obj.GetObject() != null) Print("Result: " + obj.GetObject().m_sValue1 + " " + obj.GetObject().m_sValue2);	// "bigger", non-repetitive code can be beneficial for performance and readability if (obj.MustBeTreated()) { SCR_Object subObj = obj.GetObject(); if (subObj) Print("Result: " + subObj.m_sValue1 + " " + subObj.m_sValue2); }
foreach (SCR_Object obj : list) { Method(obj); // one method call per iteration } void Method(SCR_Object obj) { if (!obj) return; Print(obj.m_sName + " has a value of " + obj.m_sValue); }	foreach (SCR_Object obj : list) // the least method calls, the better { if (!obj) continue; Print(obj.m_sName + " has a value of " + obj.m_sValue); }
for (int i = 0; i < list.Count(); i++) // list.Count() is called on every iteration { // ... }	for (int i = 0, count = list.Count(); i < count; i++) // only one list.Count() call { // ... }
for (int i, count = list.Count(); i < count; i++) { if (list[i]) // first Print(list[i]); // and second .Get(i) method calls }	foreach (SCR_Object obj : list) // foreach is faster for start-to-end iterating { if (obj) Print(obj); // no additional method call }
// declaring an 'obj' every loop generates a pointer release each time for (int i = 0, count = list.Count(); i < count; i++) { SCR_Object obj = list[i].m_Object; if (obj) Print(obj.m_sName); }	SCR_Object obj; // external declaration = only one release for (int i = 0, count = list.Count(); i < count; i++) { obj = list[i].m_Object; if (obj) Print(obj.m_sName); }
array<SCR_Object> toRemove = {}; foreach (SCR_Object obj : bigArray) { if (obj.m_bShouldBeRemoved) toRemove.Insert(obj); } foreach (SCR_Object obj : toRemove) { bigArray.RemoveItem(obj); }	for (int i = bigArray.Count() - 1; i >= 0; i--) // reverse iterating { if (bigArray[i].m_bShouldBeRemoved) bigArray.Remove(i); }
if (a) { if (b) { if (c) Method(true); else Method(false); } }	if (a && b) Method(c);
int i = 0; if (a) i++; if (b) i++; if (c) i++;	int i = 0; array<bool> conditions = { a, b, c }; foreach (bool condition : conditions) { if (condition) i++; }
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); } // or, better, one method call that initialises all of them Initialise(list); // numbering is then done inside the method, if possible Initialise(list, 1); // otherwise the starting number can be provided

Code Comments

Code comments are surprisingly not a must-have for inside code; 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.

Files Organisation

ⓘ

See Directory Structure to know how/where to organise script files (Scripts\GameCode).

• 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 together