Best practices for nyan API

[heinezen]

The API (and nyan itself) sometimes allows us to do the same thing in different ways. For common cases, we should figure out what the "best" approach is (i.e. the most resilient/readable/clean/understandable approach) and document them. We also need them for #970 when we write the converter. Best practices could be established for simple things such as object/member names or involve larger concepts.

Simple example

Removing 5 HP to a unit via a patch can be done in two ways:

• Subtract 5 from HP value: hp -= 5
• Add -5 to HP value: hp += -5

Here, the former version is probably more intuitive.

API example

Adding 20% HP to all units of a civilization can be done in multiple ways:

• Patch all HP values and HP upgrades by multiplying with 1.2
• Patch a Attribute(MultiplierModifier) with multiplier = 1.2 into every unit
• Patch a Attribute(MultiplierModifier) with multiplier = 1.2 into the civilization

Solution 1 works, but is probably too complex and does not work well with other mods. Solution 2 works with other stat modifying mods. Solution 3 is the easiest as we only need to add a modifier to the civilization. However, in comparison to solution 2 the modifier will not carry over when the unit is converted and there is no control over it during state changes (construction, damage, etc.).