GraalScript2 (GS2) Coding Conventions
 

GraalScript2 (GS2) Coding Conventions

This is a set of coding conventions and rules for use in GS2 programming. It is an adaptation of Crockford's document, http://javascript.crockford.com/code.html.

Over a script's lifetime, it will be handled by many people, making it very important to clearly communicate its structure and characteristics, making it less likely to break when modified in the never-too-distant future.


Indentation

The unit of indentation is 2 spaces. The code editor in Remote Control (RC) already handles this by changing a tab-stop to 2 spaces automatically.


Line Length

Avoid lines longer than 80 characters. If a statement won't fit on a single line, it may be better to break it up. Place the break after an operator, ideally after a comma. The next line should be indented 4 spaces.


Comments

Be generous with comments. It is useful to leave information that explains how your script works for others (possibly yourself) who will need to understand what you have done.

The comments should be well-written and clear, just like the code they are explaining. Occasional humor might be appreciated as well. Frustrations will not.

It is important comments be kept up-to-date. Incorrect comments can make programs harder to read and understand.

Make comments meaningful. Focus on what is not immediately visible. Don't waste the reader's time with stuff like:
Generally use line comments. Save block comments for formal documentation and for commenting out.


Variable Declarations

Variables should be declared before used. GS2 does not require this, but doing so makes the program easier to read.

The variable declarations should be the first statements in the function body.

It is preferred that each variable be given its own line and comment.
Avoid using global variables. Variables that don't need to be accessed outside of the function should always have a temp. preceding them.

Always use the prefix even after originally declaring the variable for clarity.


Function Declarations

• There should be no space between the name of a function and the ( of its parameter list.
• There should be one space between the ) and the { that begins the statement body.
• The body itself is indented two spaces.
• The } is aligned with the line containing the beginning of the declaration of the function.

Never use an inner function because it is not scoped and can be accessed outside of the outer function, for example:
Using an inner function like that just makes things confusing in terms of scope, because it actually becomes a global function.

If you are declaring an anonymous function (closure), there should be one space between the word function and the (.
If the space is left out, then it may seem that the function's name is 'function', which is incorrect.
Anonymous functions can unfortunately not be executed in the same statement they are declared in.


Names

Names should be formed from the 26 upper and lower case letters (A .. Z, a .. z) and the 10 digits (0 .. 9) and _.
Avoid other characters.

Do not use _ as the first character of a name. It is sometimes used to indicate privacy, but it does not actually provide privacy. Avoid conventions that demonstrate a lack of competence.

• Variables and functions should start with a lower case letter.
• Constants should be all upper case.
• Classes should start with an upper case letter

Statements

Simple Statements
Each line should contain at most one statement. Put a ; at the end of every simple statement.
Note that when declaring a variable as a function, it is still an assignment statement and must end with a semicolon.

Compound Statements
These are statements that contain lists of statements enclosed in { }.

• The enclosed statements should be indented two more spaces.
• The { should be at the end of the line that begins the compound statement.
• The } should begin a line and be indented to align with the beginning of the line containing the matching {.
• Braces should be used around all statements, even single statements, when they are part of a control structure, such as an if or for statement. This makes it easier to add statements without accidentally introducing bugs.

return Statement

return is a statement, not a function, therefore it should not use ( ) around the value.


if Statement

The if class of statements should have the following form:


for Statement

A for class of statements should have the following form:
The first form should be used with loops of a predeterminable number of iterations.


while Statement

A while statement should have the following form:

do Statement

A do statement should have the following form:
Unlike the other compound statements, the do statement always ends with a ;.


switch Statement

A switch statement should have the following form:
Each case is aligned with the switch. This avoids over-indentation.

Each group of statements (except the default) should end with break or return. Do not fall through.


Whitespace

Blank lines improve readability by setting off sections of code that are logically related.

Blank spaces should be used in the following circumstances:

• A keyword followed by ( should be separated by a space.
  
  PHP Code:

  ---

  while (true) { 


  ---

• Each ; in the control part of a for statement should be followed with a space.
• Whitespace should follow every ,

Bonus Suggestions

{}:
Use {} instead of new[0]:
This keeps thing clear by avoiding using a constructor-specific syntax for creating a data structure.

==:
Always use == instead of = when comparing variables:
Confusing Pluses and Minuses:
Be careful to not follow a + with + or ++. This pattern can be confusing. Insert parenthesis between them to make your intention clear:
is better written as:
so that the + + is not misread as ++.

Looks nice, stickied.

There was a debate somewhere in the forums a while back about this. I don't understand why you'd do something like that when you can instead do this:

Why make the engine do more work by even parsing the text to see if it should do anything with it? Comments work just as well.
This is personal preference, though generally leads to cleaner coding. I don't do it myself, but I name my variables in a way that it is easy to know where they are coming from.
It is general Graal style to have classes in all lowercase letters. I don't know of a single server that has classes with uppercase letters. Classes are not objects (like this rule was meant for). There's no reason to capitalize them.
This is personal preference.
I'm like 99percent certain this is incorrect. Someone please let me know if I'm wrong. return is not a function in any language (with similar syntax to GS2) that I know of (such as Java).
I disagree completely. It ruins the general indentation style for different blocks of code. Over-indentation is not a problem. Not indenting only hurts readability.
Why? There are times when it is perfectly okay to fall through.


I appreciate the effort you put into this, but it's focused way too much on what personal preference should be rather than clean coding standards.

Because comments like that lack a formal means of writing (as opposed to phpdoc or javadoc) and therefore could be written in varying ways, increasing variations between different coder's scripts.

When trying to say "I'm going to use this variable later", declaring beforehand it is a very natural way to do so, and avoids these inconsistencies.

I really don't think that it is a performance hit to do this during actual runtime as the script is compiled (with a YACC/Bison parser), not interpreted, therefore it would be optimized already.

Also trying to make little performance over-optimizations can lead to very nasty could in general and is a good practice to avoid when there are really no actual benefits to reap.


Classic's Dev Server does, and the coding was done by other people besides myself.

However, this is a fair point, but I don't see a reason as to not capitalize them besides increasing clarity and distinguishability between classes / objects / weapons.

Also, technically classes can be instantiated as objects with the import syntax.


I guess we'll have to wait on Stefan for that one since he's probably the only one who actually knows. I recall someone telling me this though.


It doesn't break the indentation style of indenting statements inside of a complex statement.

case is part of the structure of the switch so it does not break the indentation rule.

Also, indentation can surely be a problem when it requires excessive amounts of side-scrolling to read/alter code.


As Wikipedia states, omitting break;s is often a big source of bugs and usually the purpose is better achieved using another statement.

This is the reason why languages like C# have started to prevent people from omitting break;s.


This is a coding conventions guide. Its focus is to promote readable and maintainable code. Both of those words are subjective and most of the things stated in the conventions can not be evaluated objectively.

Although many of the things are personal preference, none of them are illogical.

This is the reason I decided to put this on the forums rather than the wiki per say, because many of this things are arguable, and are bound to be argued on. However, until there is an objective ruling on one of these things that clearly puts one above another, I believe it's important to have a firm stance on one of the options.

No, it is not. return; is a part of the language syntax, just like in most other scripted languages. Similarly, it is break; and continue;, not break(); and continue();.

Incidentally, I seem to have covered quite a lot of this already.

Alright, I assume you know the inner-workings of the engine fairly well so I'll change that.

And, I didn't even know that document existed. Why wasn't it sticked?

I have no idea :pluffy: I guess it's in the Advice thread somewhere.

IIRC, I prefer this one over Skyld's. Though, it's for the petty reason that Skyld is a fan of placing the opening brace on a new line. :cool:

You should edit the post to include things like not doing things out of code blocks, and what-not.

Didn't Zero just write a guide to switch statements that said pretty much showed efficient ways to not end each statement with a break?

Also, I like to indent my cases two spaces in, just like my if statements.

http://forums.graalonline.com/forums...ad.php?t=76294

I still don't understand why it's not stickied.

That guide just showed how to use the switch statement.

I'm saying using switch like that (usually) only leads to confusing and unfriendly code.

It would have appropriate uses when designing an algorithm where that sort of structure is integral to the script.

However, normally, when coding, falling through should be avoided.

I learned from this awhile ago, didn't say thanks. Thanks! ^^^^

Requesting unstick. This contains suggestions such as "avoid falling through", "variables should be declared", and other statements that are pretty blatantly wrong.

Personally, I don't think this is much of a clean-coding guide or whatever the Hell it's supposed to be so much as your personal preference in guide form. A lot of this stuff is very arguable, and what gives you the right to make your personal preference a standard, as this has been stickied?

Is it really that bothersome? It was written 6 months ago, and it's basically just the page he linked translated for GS2.

There's no reason to capitalise them because you can't capitalise them. When you do, the capitals get decapitalised.

Attachment 50395

Notice the window title compared to the RC output and class window? :D

Note: Sorry, I have nothing to do :(

I don't mind if this gets unstuck, but I still believe everything I wrote in here is more or less proper.

Could you elaborate perhaps?

Regarding the class capitalizing, I would change that but I can't edit this anymore.

It isn't a standard. I'm trying to appeal to people's intuitions about rules that have a logical backing.

If there a rule that work better for you, by all means use them. I'm also open to arguing any of the suggestions I provided.

I guess you could do worse than declaring variables especially considering Graal's crazy variable scopes, and while I do not do it in javascript either I can see the point considering var in a nested scope does not do what you would think it does.

And I guess falling through on switch cases is okay as long as you put // FALL THROUGH or something.

Even though most of the languages I use these days don't require it, I tend to declare all the variables I'm going to use at the beginning of a function, thanks to spending a lot of time with C.

That has it's uses, though, other than just being used to it.

For the thread to be stuck pretty much says it is the "correct" way to do things. A few points:

• Variable declarations serve absolutely no purpose to the engine, and can't possibly have any other effect except slowing it down, even if ever so slightly. Saying that all variables should be declared before being initialized is incorrect and personal preference. It is probably better to just use comments for listing variables.
• The indentation of your switch statement is wacky. This is just my personal preference, but yours is being promoted as some kind of standard.
  
  PHP Code:

  ---

  switch (variable) {
  case "value":
    // whatever
  break;
  
  case "value2":
    // whatever2
  break;
} 


  ---

  switch statements don't really have a universal format, though.
• Falling through in switch statements isn't a problem unless you work on a server with really poor scripters.
• 'default' needs to end with a break or return as well. Keep in mind it doesn't have to be at the end of the list.
• Apparently classes can't even start with an uppercase letter, and even if they could/can, that would be different than what 99% of servers are doing now.

The thread is well-intentioned, but I don't like how it tries to set the "right" way to script based on someone's ideas. I wouldn't have a problem if the thread was reposted/edited with the controversial/incorrect stuff removed. There are also some things that need further explanation, such as the return statement. The way it's worded now it could be seen that something like:
is wrong, when it's clearly not.

yea :0

Hi Chris,

For the thread to be stuck just means that people should look at it. Some guidance is better than none. (We have all seen some of the scripts out there.)

Regarding variable declarations, this is my rational behind the rule:
It makes it very clear how GS2 handles variables, and scope. As there is no block scope in GS2, this code code could be misleading:
With the above code, one (perhaps who has used C, C++, C#, Java, or the likes) may assume that temp.i would not be accessible outside of the for loop. However, this code makes it clear:
Notating the script with comments would not have this same effect.
Also, naturally, when trying to make a standard for defining your variables, why not use the one that already exists within the syntax of the language? Speed is a non-reason against this point.


Regarding the switch indentation, the style 1) prevents over-indentation, and 2) matches the indentation style of all the other statements (that is, indent all compound statements within the outer statement; the cases being part of the switch statement).


Regarding falling through, sorry, but are you calling me and many of famous professional programmers & scripters "poor"? (This includes the language designers of C#, Go, Pascal, Ruby, Ada, Eiffel, and more.) Just because a construct exists in a language doesn't warrant over-usage of it. The switch statement can be really, really misleading to even mature scripters, and totally foreign to newbie scripters.


For a break;/return; in default:, that sounds extremely weird, as default is normally only evaluated when all the other cases are exhausted (apparently I don't know switches in GS2 that well either), but I'll confirm when I get home tonight.


I would have edited the class rule by now but can't.


The wording on the return statement section is a fair point and I would edit it if I could.


Thanks for commenting Chris, and I hope you agree that a thread including this information is better than no thread at all.

Graal really needs some coding conventions. The finer points can be debated at other times. I want this thread stickied.

From what I remember reading, in GS2, the only proper time to use the switch statement is when you want to take advantage of falling through, as it's a less efficient than standard if-than-else.

Seconded.

Hey Downsider,
Although I don't claim to have any knowledge of the specific Bison language parser Stefan created nor any of its specific optimizations, in terms of switch statements in general:
A switch statement can always perform at least as well as a logically equivalent if statement.
A switch statement can perform better than an if statement when the range of values of the switch statement are sufficiently close enough to get compiled to a branch table.

I doubt that optimization has been made in GS2 though, so they are most likely equivalent in terms of performance.

I still remember reading that.

And lol @ gs2 being compared to a typical bytecode language. This is Graal. It's atypical in every way, especially the client.

dunno. you seem conceited, especially the "hi chris" "hi downsider" and the whole long-post-obviously-trying-to-intimidate deal. Bit upsetting.

Alright, here is my point of view: my thread gets unsticked (I don't even know who did it) for a reason that I totally don't agree with (minor disagreements), with no alternative put up, and I try to back up my logic.

I'm sorry if I upset you but I'm honestly trying to do something good here.

I'm upset.

I don't know, I think he's made some very good points.
And by all means, GS2 is not a bad language, Downsider, for what it's trying to do. I doubt Switch statements would be any slower than if-else logic.

WhiteDragon is someone who obviously has considerable experience and knowledge in computer science and while finer points of style boil down mostly to aesthetics and popular convention, the points he's made here are completely legitimate and helpful even if you may disagree with them.

This should be stickied.

I may have been gone for a while (and not to nitpick or jump on the bandwagon...), but this is wrong. It is not as pretty as javascript to pull it off, but it can be done.

Just because Crockford messes up doesn't mean no one should be allowed to benefit from the usefulness of switch. S'all I'm sayin'.

A few more things: javascript is a language in which appending the bracket at the end of a function is highly recommended because it has a sort of auto-complete where it puts a semicolon at the end of any line that a parser thinks is a complete statement. Placing a bracket at the end of a line avoids any confusion. GraalScript does not have this issue. Go hog wild, throw that bracket anywhere you like (where syntax allows).

The argument that X language uses Y means that Y is right for Z language is absolute nonsense. R is a statistical programming language that is C-like and return is a function in R.

This thread right now is too messy to be stickied. You've admitted there are things you would change if you could.

I would rather see a new thread stickied promoting coding standards, not personal preference.

Most things mentioned in style guides serve no purpose in the engine and are personal preference. The idea is to point out what most people's personal preference is, or should be.

That is how pretty much everybody indents switch statements.

It clearly says "should", it is not ambiguous.

No, you can definitely not call the function in the same line you define it, like so:
That would fail. I'm pretty sure this is a result of YACC not truly treating functions (and other structures such as arrays) as first-class, when they should be and would make the grammar considerably less complex that whatever is currently there, most likely.
Crockford isn't the only one I'm citing. A number of languages (see the giant list I posted a few posts back) have entirely removed the fall-through construct because of its hazard.
I'm not sure exactly what you are referring to here.
It isn't nonsense if languages X and Z have similar core assumptions.



What are you talking about?
I wasn't claiming that what I wrote was perfect and I certainly would have changed everything by now, but I don't have the permissions to.
Then go write one and stop defacing mine.

I've never said GS2 is a bad language, just said that history has shown Graalscript has never held the form of a typical language, as far as GS2's syntax being a bit atypical (Is it TorqueScript?) and it's set of features is far more complete than most scripting languages designed for a single game.

Also, I've put no thought in saying that switch statements are slower than if-then-else, simply sharing what I've previously read in the past.

The base syntax is TorqueScript, I think (I've heard it places, I could always be wrong), with lots of functions and objects for use with Graal.

If you don't like the current one go make your own instead of tearing down other people's threads.

You seem to come in here requesting it to be unstickied to try to flex your internet muscles or something instead of making suggestions to the author for improvement. And because of that you've annoyed WhiteDragon, myself, and someone else I won't name with your behavior, nice job.

Of course this post is probably full of biases.

I remember reading in a certain release note that it had rewritten the TorqueScript bytecode interpreter from scratch and thus didn't require a lisence or something.

Would be interesting for someone to clear this up.

Like I said, not so pretty...

Although that may be valid syntax (can't check right now), I don't see how that would run the function. My guess is that it would just execute:
Storing the function in a temp.suckawhat, which would evaluate to 0(?), then 0 would be stored in temp.example.

If that actually works I may have to hurt someone though since it literally makes no sense.