JPAG - JASS Proper Application Guide

[Ignitedstar]

Originally Posted by mckill2009

I didnt say anything wrong so why should I rephrase that?

Unless it means what you want it to mean, let me explain to you in detail how what you wrote may not make sense.

Originally Posted by mckill2009

If I don't follow the rules, It's OK if my spell is rejected, but if I don't follow the guidelines and still my resource is rejected, I must say that it's a total BS...

"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.

[WaterKnight]

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.

[Ignitedstar]

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?

[mckill2009]

@Ignitedstar

I think I already answered that in post #23...

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

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!...

[Ignitedstar]

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."

[Troll-Brain]

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 ?

[Bribe]

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.

[WaterKnight]

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.

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.

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.

"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.

[ShadowFlare]

Loops:

I find this easier to read:

Jass:

loop
exitwhen n > variable
    //Do Stuff
set n = n+1
endloop
set n = 0

Than:

Jass:

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?

[Bribe]

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.

[ShadowFlare]

Agreed, ugly they will always be. But here is another example:

Jass:

            loop
            exitwhen a > slength
                loop
                exitwhen b > NA
                    if (SubString(GetEventPlayerChatString(), a-1, a) == NOTALLOWED[b]) then
                        set accepted = false
                    endif
                set b = b+1
                endloop
                set b = 0
                loop
                exitwhen c > MC
                    if (StringCase(SubStringBJ(GetEventPlayerChatString(), a, a), false) == SubStringBJ(Curse[c], 1, 1)) then
                        if (StringCase(SubStringBJ(GetEventPlayerChatString(), a, a+StringLength(Curse[c])-1), false) == Curse[c]) then
                            set curse = false
                        endif
                    endif
                set c = c+1
                endloop
                set c = 0  
            set a = a+1
            endloop
            set a = 0

Nested Loops look a lot cleaner in this format, with the set and exitwhen variable on the same line, or else it would look like this:

Jass:

            loop
                exitwhen a > slength
                loop
                    exitwhen b > NA
                    if (SubString(GetEventPlayerChatString(), a-1, a) == NOTALLOWED[b]) then
                        set accepted = false
                    endif
                    set b = b+1
                endloop
                set b = 0
                loop
                    exitwhen c > MC
                    if (StringCase(SubStringBJ(GetEventPlayerChatString(), a, a), false) == SubStringBJ(Curse[c], 1, 1)) then
                        if (StringCase(SubStringBJ(GetEventPlayerChatString(), a, a+StringLength(Curse[c])-1), false) == Curse[c]) then
                            set curse = false
                        endif
                    endif
                    set c = c+1
                endloop
                set c = 0  
                set a = a+1
            endloop
            set a = 0

IGNORE TEH BJ's :P

[WaterKnight]

May be useful for the standard FOR loop to point out the actual loop body independent to the loop's framework. I usually put in a blank line though. Generally, I divide the parts more, for example by a separation line between the loops and what has to be done after another action.

[Troll-Brain]

I'm totally with you ShadowFlare, in simple incrementations loops, it just makes the code more readable.
EDIT : And with you too WaterKnight ^^

We are lacking something : a way to clearly see if a variable is global or local (and incidentally avoid conflict names, even if it's not really a problem in vJass with the private keyword).

Blizzard uses the prefix "udg_" for the user defined globals and "bj_" for blizzard jass : blizzard.j known as "GUI", should we use "g_" ?
Well, i think it's too much for many of them, but personnaly it hurts my eyes when i see a one lower case letter for a global variable such as "q" or whatever.

Personnaly i use that :

CamelCase for globals and camelCase for locals.
Usually i use verbs for functions and names/adjectives, whatever except verbs for variables, i mean the name by itself should be clear enough to make the difference between a function and a global variable.
But there is an exception the functions which returns a boolean and a boolean global variable, both could be written IsSomething. (ofc functions used in a boolexpr but where the returned boolean doesn't matter are not concerned)

Sometimes i also use This_is_a_global_variable, this_is_a_local_variable if the name is long enough.

I'm not pretending my ways are good, just suggesting something because actually there is nothing good about it.
And it's way more obvious to see a difference between a function and a global variable rather than a global and a local variable if they use all the same syntax.

[WaterKnight]

I write global variables like it was suggested here to write constant variables. Seems really much more useful for me to know if a variable is global or local than if it is constant/not or even more constant in jass meaning. There are only a few scopeless global variables that are primitive code support like NULL or INVALID for a null struct instance, ARRAY_SIZE etc. And even these could be wrapped in scopes.

I really do not like it when struct instances are compared to numbers in resources.

[Troll-Brain]

Hmm i dislike THIS_IS_A_GLOBAL.

- Because of my azerty keyboard and Windows i've to switch to uppercase / lower case for letters and "_", even if it's not the case in linux : uppercase all the way. (trivial issue i suppose i could fix it on windows :p)
- For public resources it's really bad since you can't make easily the difference between the configuration part and the "hardcoded" one, even if i'm agree the config part should just be on the top.
- static ifs (even if it's quite the same reason as said above)
- I JUST HATE IT, WHY WOULD YOU CRY ? :p