JPAG - JASS Proper Application Guide

[Bribe]

JPAG - JASS Proper Application Guide
Bettering the cause of readable source code

If you are building a map you want to submit for review, building a
spell or system to submit for public use, this guide can help to establish a
general formula for making good, readable code. The more people that
follow this, the easier it will be to read code because you know to expect
certain things and not get weird surprises like a STRUCT_NAME_LIKE_THIS.

The reason I have chosen these rules is that JASS standards defined
by Blizzard in the original form, while they still had the opportunity
to style the language in any format they chose, they chose to do it this
way. If we are to have a standard, then Blizzard's standard makes the
most sense.

These rules help to do something similar for writing your JASS code.
There has been a standard in the past for JESP, but this revives the
topic and makes points more clear. Henceforth we can refer to this
tutorial format as the JPAG format.

Naming Conventions

CONSTANT_NAMES are all capital letters and each new word
is indicated by being seperated from the rest by an underscore.
TEXTMACROS are good to write in this format, though it is not
a requirement. "constant <type> CONSTANT_NAME", however,
should follow this format, as well as the "key" type. Constant functions are an
exception, as they should still adhere to the FunctionName syntax.

FunctionNames start with an uppercase and each new word is
indicated by a new capitalitzed letter. FunctionName. StructNames,
ModuleNames, LibraryNames and ScopeNames should
also follow this format. FunctionInterface names and InterfaceNames
for lack of better placement should just be treated the same as
StructName. Though the use of either is highly discouraged because
interfaces double the code length and add unnecessary handles to your
map which in some cases also drastically slow CPU performance.

The reason why these non-JASS names should be capitalized is
just for English-language syntax and syntax of many languages.
Names are always capitalized in English. Save for variable names
and method names (reasons outlined below), keeping to this
convention is ideal if we want a uniform standard. There is also
the idea of "this is a property of 'that'" in which case it makes more
sense to write "StructName.memberName" than to write something
like "structname.MemberName" or "StructName.MEMBER_NAME"
although sometimes the latter is unavoidable but please try your
best to avoid it because it's really ugly Nestharus.

variableNames and methodNames should begin with a
lowercase letter and each new word seperated by a new capitalized
letter. This is called camelCasing. variableNames, this was designed
by Blizzard. methodNames are typically formatted like this in most
mainstream languages like C and are also formatted in such a way
with most of vJass resources, it makes sense that this should also
be the standard.

Also, short variable names are generally discouraged. A variable
should have a name that has some semblence to its purpose. If
it is for general purpose, simply writing "data" or "value" is only
fine if there is no other "general purpose" variable that might also
share such a name.

Indentation

Indentation is four spaces in JASS and every block is required
to be indented, with the rare exception of indenting the contents of
an all-encompassing library or scope because it's usually obvious
then.

Sometimes people make "exitwhen" on the same indentation as
"loop", or make "local" on the same indentation as "function". Neither
way used endorsed by Blizzard, though there are compelling arguments
to support it, if you so desire. Though I encourage to do it the Blizzard
way, doing it this other way is also permitted.

Documentation

A resource should document all of its public interface at the top
of the script, and if it has library requirements it should provide
a link to those requirements.

Obviously, in the JassHelper manual there are established
"scope" and "library" keywords. because it is controversial and
this is a global standard, I will only make the following clear:

If it is a resource that will not be required by others, for example
a spell or a fully-automatic system are not required by any other
library, it is OK if it is a scope as long as its requirements are
still linked to and declared.

Obviously if it is to be required by others, containing any form
of public API, it needs to be a library.

Use your best judgment with outlining the public API at the top
of your library.

Configuration

If your resource has things that are able to be configured, like
spell duration or FX art path, damage amount or whether to even
deal damage, they need to be easily configurable either through
dedicated functions or through dedicated constants. Some other
creative approaches to configuring your resource are sometimes
also allowed, depending on a few factors like presentation, ease
of use and with a lesser emphasis on efficiency.

Initialization Priorities

NOTE: Users of Cohadar's JassHelper can ignore this next
step for the most part as initialization is much more intuitive
in his version.

This is not clear enough to most, but here is how the order of
initialization fires in the realm of JASS:

1. Module Initializers
   
   Jass:

   module M
       private static method onInit takes nothing returns nothing
       endmethod
   endmodule
   struct S extends array
       implement M
   endstruct
2. Struct Initializers
   
   Jass:

   struct S extends array
       private static method onInit takes nothing returns nothing
       endmethod
   endstruct
3. Library Initializers
   
   Jass:

   library L initializer Init
       private function Init takes nothing returns nothing
       endfunction
   endlibrary
4. Scope Initializers
   
   Jass:

   scope S initializer Init
       private function Init takes nothing returns nothing
       endfunction
   endscope
5. InitTrig_ Initializers
   
   Jass:

   function InitTrig_MyTrigger takes nothing returns nothing
   endfunction
6. "Event - Map Initialization" GUI Initializers
   
   MyTrigger
   

   Events
   

   Map Initialization
   

   Conditions
   Actions
   
   .
7. 0-seconds game time (happens after map has finished loading)
   
   Jass:

   call TimerStart(CreateTimer(), 0, false, function OnLoad)

Rather than letting all initializers in one library or scope fire first,
initializers fire in that above sequence.

Because a modules initialize first, you should try to do everything
from within a module initializer if it initializes public API. Spells,
however, can get away library, scope, struct, InitTrig_ or Map
Initialization. A unit casting a spell from within an initializer may
bug your resource but it is too much to ask for everyone to use
module initializers for everything.

However, systems that create things which might be used by the
the public during initialization (such as a hashtable) need to use
modules to initialize, just in case. Its API is horrendous but it is
reliable.

Math Operators

Formatting math operators has been pretty freestyle for a long
time, however I owe this new addition to the guide to Nestharus
as he proposed a pretty logical way to organize operators:

One space between addition/subtraction operators, and no spaces
between multiplication/division operators. This clearly shows the
precedence of the operations.

Jass:

1 + 1 * 3 + 6 - 2 / 1 * 6
1+1 * 3+6-2 / 1 * 6
1+1*3+6-2/1*6
1 + 1*3 + 6 - 2/1*6 //Correct

[Ignitedstar]

This is so much better than Mag's. No offense to Mag, of course.

[Troll-Brain]

Indentation is four spaces in JASS

How did you come with this value ?

Sometimes people make "exitwhen" on the same indentation as
"loop", or make "local" on the same indentation as "function". Both
ways are absolutely horrible and will be laughed at upon viewing.
Your resource won't be approved by me if it employs such silliness
or similar.

Jass is not an indented based language such as python.
It's really verbose and blocks are clearly identified with their begin & end keywords.

I don't see anything bad with :

Jass:

loop
exitwhen <condition>

   // stuff

endloop

It highlights when the end of the loop occurs.
Quite same for locals, with a new empty line between the function declaration and the local variable it seems fine.
Even if personnaly i prefer to add an indentation for locals declaration.
I also prefer to add a new empty line just after the function declaration, for the readability of the arguments and which type of value is returned.

At least it's a matter of opinion, it's 100 % subjective and i don't see anything funny, nor silly in that.

[Bribe]

The point is to coincide with the existing standards that were set by Blizzard.

Their entire common.ai library, cheats.j library and blizzard.j libraries were formatted this way. To change it now "just because" goes entirely against what these guidelines stand for.

Your argument could be manipulatd with JASS "not being indentation based" into arguing for no indentation at all. It's a very slippery slope especially with people like yourself who have preference-based arguments for "doing it your own way". It is this kind of thing that I recommend for building your own map, but for public resources, it's best to stick to uniform design.

I have personally found many of your JASS snippets very strangely formatted and with too much whitespace, so it's no surprise to me that you might have some objection to a certain format.

[Troll-Brain]

While i'm agree it's fine to follow Blizzard's standard, i still don't see anything silly or funny with it (exitwhen and locals).
But ok it doesn't follow the standard, i have to agree with that.

Also i've never talked about no indentation at all, plz don't use false logic.

And subjectivity is subjective.

Btw, you haven't answered to my first question (but since i've edited my post maybe you haven't seen it yet).

[Bribe]

It is obvious where the value came from and I made that clear by quoting the sources.

[Troll-Brain]

But blizzard.j is the root of the devil :o (joke)

[Magtheridon96]

This is so much better than Mag's. No offense to Mag, of course.

None taken ;)
I'm already in the process of changing it to a Speedfreak tutorial ;P

The English language has certain syntax like sentences, commas
and paragraphs, and tends to follow a general syntax pattern in
printed works. The content of the writing is obviously very diverse
but the way it is presented is the same, even though there is tech-
nically "nothing to stop you" from screwing up your grammar and
writing your message anyway. It's just no guarantee that everyone
can make sense of it and/or be able to take you seriously, specially
if u rite lyk thiz.

Booooooooring XD

[Bribe]

Originally Posted by Magtheridon96

Booooooooring XD

That describes one external perspective of my lifestyle in a nutshell.

[WaterKnight]

Originally Posted by Bribe

The point is to coincide with the existing standards that were set by Blizzard.

Their entire common.ai library, cheats.j library and blizzard.j libraries were formatted this way. To change it now "just because" goes entirely against what these guidelines stand for.

Blizzard does not write in vJass and they create a lot of swapping function wrappers. Should we mimic that, too?

But that is why I hardly upload resources/only tell of the concepts as I cannot match up the standards and have too big of a custom environment.

[Magtheridon96]

That describes one external perspective of my lifestyle in a nutshell.

I thought that paragraph was really good actually :p
I usually just go directly to the point. (Which isn't always good)

[Troll-Brain]

This behavior doesn't really work with womans (unless you have some Benjamin Franklin with you).

[Magtheridon96]

flood

Ofcourse it works with teh womens ;D
Directly to the point: "Hey, wanna fuck?"

[Ignitedstar]

Can we have a thread where people keep their pants on WHILE talking about programming? xD

ANYWAY, as much as I see WaterKnight's point, I'd have to say that what you said is a bit unfair. Apparently they use them for GUI when all they do is redirect to the native. We don't know why they made those swapper functions, and even if we could ask them, they would probably not tell us since if you think about it, JASS is... ten years old, now? Somewhere around there.

[WaterKnight]

But that means that we can completely neglect blizzard.j. As for me, I even neglect natives because of having my own wrappers for everything, only writing them at the lowest levels of the header. Now, I see that this does not work as a lot of people use natives in the public resources and the requirements should be manageable. Maybe, at some point, the native functions could be renamed.

In the end of the day, the conventions shall be beneficial, so I do not think that an old standard laid out by Blizzard would last forever.

Also have to repeat my question from the other thread: Why CONSTANTS_VARIABLES in big and non-constant globalVariables in camel? Other than Blizzard does it this way.