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. DID YOU KNOW - That you can unlock new rank icons by posting on the forums or winning contests? Click here to customize your rank or read our User Rank Policy to see a list of ranks that you can unlock. Have you won a contest and still haven't received your rank award? Then please contact the administration.
    Dismiss Notice
  3. Ride into the sunset in the 32nd Modeling Contest.
    Dismiss Notice
  4. This adventure has come to an end. Congratulate our heroes in the 16th Mini Mapping Contest Results.
    Dismiss Notice
  5. From the gates of hell, the 5th Special Effect Contest Results have emerged.
    Dismiss Notice
  6. Race against the odds and Reforge, Don't Refund. The 14th Techtree Contest has begun!
    Dismiss Notice
  7. 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:
    8,158
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    I think then that this should just be a set of standards that can be
    taken at face value, that do not have to be implemented but are
    rather "one option of doing it".

    I think comparing this to the English langauge syntax was a big
    straw man argument, now that I dig a little deeper.
     
  2. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,033
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    You may force these rules all the way you like. You are the moderator and have to apply a structure with your staff.

    You created an open thread for it and reasoned back, implying that you actually want to discuss the matter. Now do not be so whiny when people tell their point of view. Also just a few have replied yet.
     
  3. mckill2009

    mckill2009

    Joined:
    Mar 10, 2009
    Messages:
    4,696
    Resources:
    34
    Maps:
    5
    Spells:
    27
    JASS:
    2
    Resources:
    34
    If I dont follow the rules, I'ts OK if my spell is rejected but if I dont
    follow the guidelines and still my resource is rejected, I must say that it's a total BS...

    got it right, coz seems like the guidelines you imply is like "you must do this", instead of "i suggest/recommend this"...
     
  4. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    8,158
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    Well the idea here has been to make it a rule, yeah my choice of
    the word "Guideline" was ill-chosen because it implied that it was
    optional.
     
  5. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    A forum is not a a democracy anyway, make it as a (v)Jass submission rule.
    Same for short (obfusced) names, they shouldn't be tolerated, if the author really care about it, he could post this "optimized" version together with the one which is readable.
     
  6. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    Um, I think you need to rephrase that because this sentence says something that I don't think it should be saying. Mind telling us what this resource was? Not everything needs to be a public resource. Especially if it's easy to make.

    @WaterKnight: From what I've been reading, I understand Bribe's point very clearly, though yours is a little foggy. Keeping a standard is what a person wants to do if you're submitting a resource to a public space, like the Hive. There's a reason why JESP got called a standard.

    People can code stuff in Warcraft in any way they want. Bribe's point was never "You HAVE to do this a certain way." BUT, if somebody is planning on submitting their code as a resource, it needs to follow rules. This is why he (and to a point, Mag) created this thread. This way, people who submit something don't have to explain how things work a thousand times just because the coding language and/or format is different.

    But then, you're saying that there's nothing wrong with the standard; it's just that Blizzard made inefficient ways of coding through blizzard.j (and common.j too?) and it should be avoided. It's true that Blizzard made the language, but from my knowledge, anyone who codes in JASS is always told to avoid blizzard.j as much as possible because of its general inefficiency and nonsensical functions. At least, this is what I was told when I started learning JASS five years ago.

    Scopes, modules, libraries, and structs were introduced by Vexorian and vJass. There's also ZINC and whatever-else that has been made. I believe one of the reasons why ZINC was made is because, well... Zinc Is Not C. And since Jass is based off C... In any of these cases, none of these additions weren't made by Blizzard. Therefore, I don't think these are even relevant to the argument because I believe we're talking about Blizzard's functions.

    My deduction raises a contradiction. You two (WaterKnight and Bribe) generally agree on the same thing. Blizzard.j is flawed, any JASS user would agree (any decent programmer would probably agree-- but don't forget that JASS is nine years old). I honestly don't believe there was an argument to begin with. So how did this happen? If I'm wrong anywhere, feel free to point it out.
     
  7. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,033
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    I understood that Bribe wants to enforce a standard for public submissions, which I generally agree on. At least to determine what can be featured by the site (be approved).

    The starting post presents a model for these guidelines from what Bribe has in mind. And this model in parts was criticized and/or scrutinized/questioned (which seems legitimate since its a normal tutorial thread open for repliers and to be reviewed). As a counter argument to some of these points, Bribe mentioned his proposed ways would be better because of adhering to Blizzard's style whereas I tried to invalidate the sense of this point by displaying some of its flaws we all agree on and that we already use vJass (which this tutorial includes), so people do not actually stick to old patterns of Blizzard in whole and there can be better ways, especially in consideration of a progressing map making process. Was not so long that LUA scripts were not permitted, was it?
     
  8. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,428
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    Guidelines are nice, they make code become uniform, and so long as the guidelines are proper, they make code become more readable.

    As for the guidelines, I agree with what Bribe has stated.

    For indentation, I believe the reasoning for 4 spaces is the fact that it is the amount of spaces you receive from one press of the tab key in TESH. Of course, that was not the initial reasoning, but since most JASSers use NewGen coupled with TESH, it makes sense that we make the guidelines in accordance to what is done most.

    I suppose it isn't necessary to restrict it, but you have to keep in mind that we are looking for uniformity. :)

    As with the other stuff. The easiest way to achieve uniformity is to use what is used most. Allowing too many variations obviously won't achieve the same results. All of the arguments are completely valid, and it is fine to argue to rework the guidelines if necessary, but for now I believe these will do, no?

    I'll leave this in submissions for a while for discussion, unless we get a flow of hearty approvals in which case I'll gladly move it. :p
     
  9. mckill2009

    mckill2009

    Joined:
    Mar 10, 2009
    Messages:
    4,696
    Resources:
    34
    Maps:
    5
    Spells:
    27
    JASS:
    2
    Resources:
    34
    I didnt say anything wrong so why should I rephrase that?...anyway it's up
    to them if they wanna make it a rule, it's OK for me anyway but until then
    it's still a guideline, not mandatory...
     
  10. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    8,158
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    It's not going to be a rule unless there is overwhelming support to make
    it one.

    So far there isn't. So for now this is "a very recommended way" to write
    code, and if someone has any alternative suggestions on a standard way
    to write their code then their input is appreciated.

    So far the arguments against this are basically "no standards at all" and
    not so much arguments against any particular point while supporting any
    others.

    I can see how vJass-type things such as library, module, struct, scope,
    etc. might be contested, for example, but no one has given me very
    constructive criticism here, for example it could be argued I should just
    leave the vJass-exclusive things out and only clarify the normal JASS
    things.
     
  11. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    Unless it means what you want it to mean, let me explain to you in detail how what you wrote may not make sense.
    "If I don't follow the rules, it's okay if my spell is rejected." Nothing wrong here. It's the next sentence.

    If I don't follow the guildlines and still my resource is rejected, it's total BS. Read that carefully and you'll realize there is something that's... off.

    What you wrote says that what you make doesn't follow the guidelines for a resource, they get rejected and it's BS.

    Of course the resource would get rejected. It doesn't follow the guidelines. This is a double negative-- two negative statements put in the same sentence are making a positive statement. In other words, you expect resources that don't follow guidelines to be approved. In addition, it raises the unfortunate implication that you may also expect resources that do follow the guidelines to be rejected.

    I believe that don't is supposed to be do. It makes tons of more sense if you follow the guidelines, but your resource is rejected.

    ---

    @Bribe: I think that decision is too rash. You've done a great job; the first three paragraphs make amends to the issues that have been presented. I don't see anything wrong with a JPAG, but this is coming from someone who has been taught JASS using JSEP. I'm used to seeing submitted spells being read this way.

    The purpose of this tutorial is to show how people should submit their resources if they want them approved; It says nothing about how people should code their work otherwise, especially if they're not going to submit anything.

    The reason why the things written in the tutorial are there is for consistency. It makes code easier to read. If another can't read your code, but you're submitting it, there's no point. Why submit a resource that no one can read? Or use, for that matter? Of course, when it comes to using stuff, that's what comments and instructions are for. That's the discretion of the maker, not the user.

    I don't even remember Bribe writing that JPAG will replace JESP. A person can use either. I really don't see a problem.

    ---

    @WaterKnight: You keep (or kept) stressing the point of "why are you using Blizzard's standard when it's not normal". Well then, what do you mean by normal? All programming languages use different formats when it comes to syntax. Unless you're trying to say that Java and Python look identical. If you're always using your own wrappers anyway, why this is a problem? And I have to ask: Do you plan on submitting anything? If no, don't worry about it.

    This piece may sound very childish, but I have to ask. You keep asking people why use something like Blizzard's syntax for certain things, but I can equally ask you, "Why not?" I just don't see the point in fighting over whether a constant should be named this_constant_does_something over THIS_CONSTANT_DOES_SOMETHING. The constant will still do the same thing, it's just one is all capitals and the other isn't. Either one isn't saving any bytes. "Why are we doing this way?" is a good question, but "why is it a problem when JASS is already like this?" is probably a better question.

    If it really bothers you so much that it's completely unacceptable, then I turn over to the answer I gave Magtheridon in his 'Jass for Speedfreaks' topic: "Write your own programming language for Warcraft." Or, simply enough as what I've been trying to say for the last couple of days: "Don't submit anything to the Hive." There are plenty of other sites other than the Hive that will accept your resource, like the TheHelper.

    If it doesn't bother you that much, then I really would like an opinion with decisive evidence of why the method you suggest is better for people whom submit their resources than what Bribe has already written.

    I probably sound like an asshole at this point, but the point stands: I don't just understand how this is such a big deal.
     
  12. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,033
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    mckill2009 meant it that way that guidelines should not be obligatory because he/she understood the word "guideline" as a loose rule you only may stick to. Bribe also agreed on this and admitted the term could have been misleading as he actually wanted to enforce it to be a serious, fix law.

    Where have you read that I think of Blizzard's style as abnormal? I have not compared it to any other language, nor claimed that an indentation of 4 is good or bad for example, only that being an "old and original" style might not be the most crucial argument to keep it. If Blizzard's .j files were totally obsfucated, would you still uphold it? Now, we can talk about what were the thoughts and benefits Blizzard saw while developing this language and compare it to our targets and current situation. As I said, the scene evolves, so the whole perspective might change in time. Though, and this was mentioned just some posts ago, I agree to the demand to (at least temporarily) maintain backwards compatibility, as many of the current uploads are in traditional format.

    The references to me using wrappers should have illustrated that some other style may be better matching with newer resources and that the native functions being OfThisFormatAtTheMoment may be up to us to change or to decide in future. So this would be no mandatory barrier.

    I have asked questions to Bribe for the simple reason that he made suggestions and his reasoning from the starting post did not convince me. Would you not have asked me if I announced that all vars should have the suffix "Var" in it? If you want to insist on your point, that's okay, if you elaborate and try to reason it, be ready for backfire. And the big deal was more like in the art of debating.
     
  13. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    If he meant it that way, I would have certainly hoped he wouldn't need someone else to elaborate that for him. I can speak from experience to say that when bypassing occurs in writing, 90% of the time it's not the reader's fault. I want to see him type that himself in his own words.

    What you've written is pretty much the reason why I posted a whole mess; I was confused. There are a few finer details that I'd like to discuss, but I really don't have time to write something that will take me another three hours. I was under the impression that there was a difference in opinion because of a problem. But there is no problem. This lonely fact makes my entire argument null. The reason why I wrote all of that was because I was falsifying my own assumption; I needed to verify whether or not a problem existed.

    The only reason why any of this seemed to have happened is so people can acknowledge another person's opinion. This certainly isn't a bad thing, but I'm the kind of person who would like some progress out of a conversation. So far we haven't accomplished anything. I'm sorry if this offends anyone, but so far my brain is translating this as a waste of time. So are we actually going to do anything?
     
  14. mckill2009

    mckill2009

    Joined:
    Mar 10, 2009
    Messages:
    4,696
    Resources:
    34
    Maps:
    5
    Spells:
    27
    JASS:
    2
    Resources:
    34
    @Ignitedstar

    I think I already answered that in post #23...
    furthermore, it was clarified in post #24 that it's optional...
    Bribe & WaterKnight understands what I mean, why can't you?...
    lastly, I'm not really good in english so pls pardon me if I have errors in writing, peace buddy, case closed!...
     
  15. Ignitedstar

    Ignitedstar

    Joined:
    Jun 30, 2004
    Messages:
    160
    Resources:
    0
    Resources:
    0
    It doesn't look like you were paying attention to my explanation of why what you wrote could be taken the wrong way. But since this is the Internet, I guess that's expected.

    I think it's funny how the conversation ends with "So are we actually going to do anything?"

    I'll take that as a, "No."
     
  16. Troll-Brain

    Troll-Brain

    Joined:
    Apr 27, 2008
    Messages:
    2,372
    Resources:
    1
    JASS:
    1
    Resources:
    1
    I think it's not good that a moderator has his own unofficial rules for a submission.
    Indeed, Bribe has clearly said that he won't approve a code which doesn't follow these rules.
    And honestly they are good enough, so why not make them official ?
     
  17. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    8,158
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    I have re-written some of the more contested parts and re-iterated
    my arguments to better present why this should be the standard. I
    appreciate anyone's time to give this another looking over to see if
    there are still things too controversial to be included.
     
  18. WaterKnight

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,033
    Resources:
    5
    Maps:
    1
    Tutorials:
    4
    Resources:
    5
    "Names always start with a capital letter according to English. Of course, this rule only applies to the things I had in mind and sticks to the classic pattern I have no idea of why it was turned out this way."

    May I help out with my thoughts what could be possible reasons for these standards? This does not mean that it would explain it all but could think part of.

    The capitalization illustrates that the identifier is globally accessible. When writing a struct, you can only enter it from outside via the struct name or an instance. All members are subordinates, so they begin lower-case. Often, inside, users only write "call doSomething" without "this." or "." as an abbreviation because its visible by the lower-case already that we are still in the same scope. Appended words start big again to recognize them. CONSTANT_NAMES are yelled to demonstrate their solidness and to outline a contrast but I must say I do not use them in Wc3 very much, as they have very limited use in jass and most times I know from the name if it has to be a constant or not, or have to declare them as pseudo-constants, defining them once in init function/method. Functions/Methods have imperative names because they should do something. Variables are more passive attributes that are limited to themselves/do not have the might. An exception might be operators like myVar = value but I regard this as a listener, reactions follow on the variable's setting.

    For the reasons mentioned, I would not write scopeless globals thisCase for example.
     
    Last edited: Oct 6, 2011
  19. ShadowFlare

    ShadowFlare

    Joined:
    Jun 30, 2008
    Messages:
    552
    Resources:
    0
    Resources:
    0
    Loops:

    I find this easier to read:

    Code (vJASS):
    loop
    exitwhen n > variable
        //Do Stuff
    set n = n+1
    endloop
    set n = 0


    Than:

    Code (vJASS):
    loop
        exitwhen n > variable
        //do stuff
        set n = n+1
    endloop
    set n = 0
     


    The first example seems easier for me to find exactly where the variables I want to change are.

    Perhaps make this the standard?
     
  20. Bribe

    Bribe

    Joined:
    Sep 26, 2009
    Messages:
    8,158
    Resources:
    25
    Maps:
    3
    Spells:
    10
    Tutorials:
    3
    JASS:
    9
    Resources:
    25
    For loops, after letting go of (some of) my ego recently the exitwhen statement being on the same line of the loop is pretty good, though the "set" statement does not look good there. That's why I don't define it as such a key rule. I say in this one it's a matter of preference, because JASS loops are so ugly no matter what we do.