1. Updated Resource Submission Rules: All model & skin resource submissions must now include an in-game screenshot. This is to help speed up the moderation process and to show how the model and/or texture looks like from the in-game camera.
    Dismiss Notice
  2. The 15th Mini-Mapping Contest came to an end. The Secrets of Warcraft 3 are soon to be revealed! Come and vote in the public poll for your favorite maps.
    Dismiss Notice
  3. The 12th incarnation of the Music Contest is LIVE! The theme is Synthwave. Knight Rider needs a song to listen to on his journey. You should definitely have some fun with this theme!
    Dismiss Notice
  4. Join other hivers in a friendly concept-art contest. The contestants have to create a genie coming out of its container. We wish you the best of luck!
    Dismiss Notice
  5. Check out the Staff job openings thread.
    Dismiss Notice
Dismiss Notice
60,000 passwords have been reset on July 8, 2019. If you cannot login, read this.

JPAG - JASS Proper Application Guide

Discussion in 'JASS/AI Scripts Tutorials' started by Bribe, Sep 27, 2011.

  1. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    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.

    AMENDMENT: Added on 25 Feb 2016 by Bribe:

    Creation and destruction of artificial types should match the naming conventions set by Blizzard and Vexorian. Struct methods should be named "create" or "destroy". Other functions which try to serve the same purpose should begin with Create or Destroy.

    There is another naming convention which should be encouraged: adding and removing. These should be reserved for container-type syntax. In JASS, you have
    GroupAddUnit, GroupRemoveUnit, ForceAddPlayer, ForceRemovePlayer
    and others. The naming convention should contain the words add and/or remove when you are working with structures like linked list, linear stacks, Tables and any other "containing" element which may be utilized or invented.​

    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
      Code (vJASS):
      module M
          private static method onInit takes nothing returns nothing
          endmethod
      endmodule
      struct S extends array
          implement M
      endstruct
    2. Struct Initializers
      Code (vJASS):
      struct S extends array
          private static method onInit takes nothing returns nothing
          endmethod
      endstruct
    3. Library Initializers
      Code (vJASS):
      library L initializer Init
          private function Init takes nothing returns nothing
          endfunction
      endlibrary
    4. Scope Initializers
      Code (vJASS):
      scope S initializer Init
          private function Init takes nothing returns nothing
          endfunction
      endscope
    5. InitTrig_ Initializers
      Code (vJASS):
      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)
      Code (vJASS):
      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.

    Code (vJASS):

    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
     
     
    Last edited: Feb 25, 2016
  2. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    This is so much better than Mag's. No offense to Mag, of course.
     
  3. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    How did you come with this value ?

    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 :

    Code (vJASS):
    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.
     
  4. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    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.
     
  5. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    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).
     
  6. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    It is obvious where the value came from and I made that clear by quoting the sources.
     
  7. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    But blizzard.j is the root of the devil :eek: (joke)
     
  8. Magtheridon96

    Magtheridon96

    Joined:
    Dec 12, 2008
    Messages:
    6,006
    Resources:
    26
    Maps:
    1
    Spells:
    8
    Tutorials:
    7
    JASS:
    10
    Resources:
    26
    None taken ;)
    I'm already in the process of changing it to a Speedfreak tutorial ;P

    Booooooooring XD
     
  9. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    That describes one external perspective of my lifestyle in a nutshell.
     
  10. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,021
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    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.
     
  11. Magtheridon96

    Magtheridon96

    Joined:
    Dec 12, 2008
    Messages:
    6,006
    Resources:
    26
    Maps:
    1
    Spells:
    8
    Tutorials:
    7
    JASS:
    10
    Resources:
    26
    I thought that paragraph was really good actually :p
    I usually just go directly to the point. (Which isn't always good)
     
  12. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    This behavior doesn't really work with womans (unless you have some Benjamin Franklin with you).
     
  13. Magtheridon96

    Magtheridon96

    Joined:
    Dec 12, 2008
    Messages:
    6,006
    Resources:
    26
    Maps:
    1
    Spells:
    8
    Tutorials:
    7
    JASS:
    10
    Resources:
    26
    flood
    Ofcourse it works with teh womens ;D
    Directly to the point: "Hey, wanna fuck?"
     
  14. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    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.
     
    Last edited: Sep 28, 2011
  15. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,021
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    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.
     
  16. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    There is no other reason. If everybody does their code differently then it's
    spaghetti code all around, and then for each resource there is a big learning
    curve just to understand how it works.

    Rather than being biased and making up my own layout, which as has been
    touched on would not be objective any more, Blizzard were the ones who
    actually designed the syntax of the language and this is how they presented
    it to us, from a time when they could have done anything they wanted with
    it.

    Obviously not everyone has the same preference in art but in the end there
    are some things that should be standards in programming because otherwise
    we are all doing things differently and the learning curve is huge.

    Obviously you do not have to re-code your resources to conform to such a
    standard but a big factor for me in approving resources is ease of use and
    ease of implementation (hence why there are still so many Nestharus codes
    still pending).

    Your resource may be so easy to use and implement already that there may
    be an exception made to the rules, but from what I have seen strang coding
    style and strange API tend to go hand in hand.
     
  17. mckill2009

    mckill2009

    Joined:
    Mar 10, 2009
    Messages:
    4,696
    Resources:
    34
    Maps:
    5
    Spells:
    27
    JASS:
    2
    Resources:
    34
    He meant like this...
    Code (vJASS):

    function four takes nothing returns nothing
    12341234
    12341234
    12341234
    endfunction
     


    in the end it's up to the user/coder on how he will create his code whether it'll be for public or for self...a moderator can't just reject a spell/system if he writes like this...
    Code (vJASS):

    private function DR_DIES...
     


    instead of this...
    Code (vJASS):

    private function DrDies...
     


    the rules simply do not imply readability...But I do agree that the second method is more presentable than the first one...
     
  18. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,021
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    I did not speak out against a standard, only said that the standard should be well chosen and does not have to cling to Blizzard. vJass and JNGP would not have been developed if people did not feel the necessity in advancing.

    @mckill2009: And Troll-Brain probably meant to ask why precisely 4 spaces and not 1 or 2 or 3 or 5...
     
  19. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    7,947
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    I swear there is more objection to what has been written in this thing when I'm just outlining the most basic things.

    Obviously I've struck a nerve too deeply. Controversy was not the intention here.

    Perhaps I should rename this to something like "General Guidelines for Standard Readability for people who are looking for such a thing".
     
  20. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,021
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    So what did you expect for answers in this thread?

    I repeat that I am not against the general idea but you have proposed a tutorial and the contents and detail can be discussed. It is the same with other tutorial threads and presented resources.

    @mckill2009: Of course, a moderator can reject this if it does not obey the guidelines.