GPAG - GUI Proper Application Guide

[IcemanBo]

GPAG - GUI Proper Application Guide

1. Introduction

GPAG defines uniform standards and conventions that we strive to apply in our GUI submissions.
The goal is to come on the same page for coding style, and to ensure clean and readable triggers.​

2. Naming Conventions

2.1. Prefix

To avoid name collision each system is asked to define a PREFIX. The spell/system PREFIX is a constant name and should be resource descriptive. For example, if it's a fireball spell, the prefix might be "FIREBALL" or "Fireball". It's up to you, if you decide to write the prefix LIKE_CONSTANTS, or like VariableNames -- choose what you prefer. The PREFIX length should be at least 3-4 characters long, or even more, to ensure some uniqueness. Also, no matter what variables your system creates, all of them must be advanced by the PREFIX and an underscore _.​

​

2.2. Variables

VariableNames start with a capital letter and also each new word is indicated by a new capitalitzed letter. The name itself must be descriptive for the variable's purpose. - What does this mean? When you work with temporary variables it's totally okay to give generic names, like: "Unit, String, Real, Point". However, when the variable usage is specified, then its name should be specified as well. So then, the name style changes from generic to specific. Here are examples:

Generic/Temporary usage Unit Real

Specific Usage Caster/Target Damage/Distance

The final variable name, combined with the prefix, looks like: PREFIX_VariableName:

FIREBALL_Caster
FIREBALL_Duration​

​

2.3. Constant Variables

CONSTANT_VARIABLES are exclusivly written in capital letters and each new word is seperated with an underscore _ . Constant variables are only set once, usually after map loading, and the capital letters indicates to never change the variable's value. They are usually used to define some system default datas to get the system working.

The final variable name for constants, combined with the prefix, looks like: PREFIX_CONSTANT_VARIABLE.

FIREBALL_ABILITY_ID
FIREBALL_ORDER_ID​

​

2.4 Triggers

The same principle from variables applies to your triggers. The trigger's name will result in: PREFIX TriggerName.
The TriggerName should be descriptive, similar like variable names. Example names for triggers for a fireball spell:

FIREBALL Setup -> here the user can find everything config related.
FIREBALL Cast -> this is the trigger with obivously "A Unit Casts" event.
FIREBALL Periodic -> this trigger runs periodically. Probably used for fireball movement.​

​

2.5 Object Data

For object editor data, except for items and doodads, there exists a field named "Text - Editor Suffix". This field comes handy when your system uses custom object data, so you can use it to put in your PREFIX there. The idea behind is that the user will always be able to easily distinguish which object data belongs to which system or spell.

There are cases though, where it doesn't really make sense to use a object suffix. For example, when we import a "Fireball" spell and the prefix is "Fireball".
The name result in object editor would look like "Fireball (Fireball)", so you see that it doesn't really help anyone to distinguish data.
However, when the object editor data differs from the prefix, then using "Text - Editor Suffix" is indeed often helpful and asked for.​

3. Documentation

Documentation is something good and each coder's friend. However, only when done correctly. We don't need to know uninteresting details like
"Here I set my integer variable." We can see that! Instead, it's much more important to understand why/for what you do something. We want to understand the purpose.
You usually don't need to document each single line, but instead, try to describe a whole code block in a concise manner, always when you think that some information could be helpful at that point. The bigger the code gets, the more benefits you will have from comments.​

4. Configuration

Configuration needs to be seperated from the system's core code. That's mostly done with putting all config-related parts into a seperate trigger.
Usually, things like:" Damage, Size, Durations, Radius, Effects, ..." are meant to be configured. The user doesn't care about the system's core code and he only wants to know what he should change to get the code properly working. Therefore, also the configuration always requires a proper Documentation to ensure that the user easily can follow and understand everything related.​

5. Last Word

We prefer following GPAG, but at same time we won't blindly enforce it. So in case your personal standard sligthly differs from GPAG, it may be accepted as well, as long as clean and readable code is ensured. In case of uncertainties feel free to inquire about it with the respective moderators in Staff Contact or discuss it here in this thread.​

 

[Chaosy]

Prefixes:
Firstly, I do not think 4 characters+ is needed. After all, with just two characters (Fireball > FB) you still have 729 possible combinations. So in theory, 729 GUI spells and systems. I mean sure you might be a tad unlucky and get a duplicate, all I am saying is that it's not that big of a deal. Also, I think consistency is more important than how you actually name them. So you don't do something like:
FB_a
FB_b
FiBa_c
FiBa_d

My last point goes for variables as well. As long as all your variables are the same, all fine.


Constant variables:
This may make sense for someone who likes jass, but I do not think this is something to be enforced for everyone.

Suppose I agree with everything else.

 

[KILLCIDE]

but I do not think this is something to be enforced for everyone.

We prefer following GPAG, but at same time we won't blindly enforce it. So in case your personal standard sligthly differs from GPAG, it may be accepted as well, as long as clean and readable code is ensured.

 

[IcemanBo]

"2 letters" -> " much combinations"
--
well, in theory if you count the systems how many you import, then it might be enough. But practicaly also often same letters are chosen, and some aren't (like "ZZ", "YY", .. etc you probably won't find often)

Yeh, this "constant" style in GUI is/was practicaly not often used, but when I tried it out, it was really a bit better to read in the GUI core code, because one could immediatly see that
this variable is not instance-specific, but just a default constant.

 

[KILLCIDE]

Not sure why this is still sitting in Submissions. Approved and stickied!

 

[Daffa]

I find Periodic better with Loop instead.

 

[JC Helas]

In system part should we document it too? Or maybe only those part which need to explain because we have our own acceptable style?

 

[IcemanBo]

Yes, it's usually useful if the system core code has some documentation. Documentation has a different meaning, depending if it's made in the config, or the core code.

The core code
Here documentation is used to understand how the system even works.

The configuration
Here documentation is used to understad how to take usage of the system.

Readabilty and and documentation will help the reviewer, yourself, and just any reader that comes to read your code, and may safe so much time that's invested to understand it in future.

 

[Map Designer]

What about spell pack conventions?
If pack has 4 spells, should they all have 1 prefix or 4 different ones?

LIKE_CONSTANTS, or like VariableNames

Is this true? it seems to me that you wanted to say like_VariableNames

 

[IcemanBo]

it seems to me that you wanted to say like_VariableNames

No, I didn't want to say that. Why?

What about spell pack conventions?

If all spells of a pack have exactly same prefix you need to have unique normal names, which would be not the sense. Example "ABCD" is the spell pack prefix, then there can be only one ABCD_ABILITY_ID, etc. If you would like you could have 2 prefixes, like ABCD_SPELL1_ABILITY_ID, ABCD_SPELL2_ABILITY_ID, etc - to show those spells are like in same group.