Graal Forums  

Go Back   Graal Forums > Development Forums > NPC Scripting
FAQ Members List Calendar Search Today's Posts Mark Forums Read

Reply
 
Thread Tools Search this Thread Display Modes
  #1  
Old 10-18-2005, 05:37 PM
Skyld Skyld is offline
Script-fu
Skyld's Avatar
Join Date: Jan 2002
Location: United Kingdom
Posts: 3,914
Skyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud of
Send a message via AIM to Skyld
Script Formatting Guidelines

It has reached my attention lately that a number of people have been neglecting to keep their scripts in a sensible state. As a result of this, I have written a set of guidelines for scripting. They seem to have adopted the name "SSI-GS2".

What are the advantages of following these guidelines, you say? It's quite simple. People may be more willing to help you with your code. See section B.1.

A. Definitions
  • A.1. Function: A predefined block of code, which can be executed when needed and can be given parameters since gscript2
  • A.2. Variable: An object that's value can be changed
  • A.3. Variant: A variable which automatically assumes the type of data depending upon the data it is given
  • A.4. Event: Triggers which the scripting engine uses to execute predefined code (usually an Event Block)
  • A.5. Event block: A predefined block of code, written to be executed when a certain event occurs


B. General Formatting Guidelines

B.1. Importance of Readability
The readability of your code is very important, for more than one reason:
  • It makes it much easier for others to read and understand your code
  • It makes it much easier to spot syntactical errors, and often simple logic problems
  • It is generally much nicer to work with

B.2. Scripting Style
Most people usually have their own style of scripting. However, sometimes these differences make it harder to understand code. Therefore, it is a good idea to stick to these guidelines when formatting your code.
  • B.2.1. Indentation

    Indentation should always be consistent throughout your code. Two whitespaces per open block are effective.
    This example is good:
    PHP Code:
    //#CLIENTSIDE
    function onCreated()
    {
      
    showimg(200"testimage.png"100100);

      if (
    player.30)
      {
        
    changeimgcolors(2001001);
      }

    However, this example is bad:
    PHP Code:
    function onCreated()
    {
    showimg(200"testimage.png"100100);

    if (
    player.30)
    {
        
    changeimgcolors(2001001);
    }

  • B.2.2. Spacing

    Spaces between parameters, operators, etc, should always be consistent. One whitespace is usually best.
    Please note that when using commands in old gscript, this is not always applicable.
    This example is good:
    PHP Code:
    function onCreated()
    {
      if (
    player.account == "Skyld" || player.account == "GrowlZ1010")
      {
        
    player.chat "Woah.";

        
    triggeraction(00"serverside""Weapon""action");
      }

    And the following example is bad:
    PHP Code:
    function onCreated()
    {
      if (
    player.chat=="Skyld"||player.chat=="GrowlZ")
      {
        
    player.chat="Woah.";
        
    triggeraction(0,0,"serverside","Weapon","action");
      }

  • B.2.3. Braces Edited

    Braces are used to fit more than one operation into an event or function. It is usually good practise to use them even if you only have one line of code in your function.

    However, to promote readability, you should remain consistent on whether your braces are on a new line or directly follow the function definition/statement.

    Some argue towards having braces on their own lines (imagine that you have a long script with a lot of braces being used. Reading over it with braces on their own lines not only makes it easier to spot where blocks are opened and closed, but it makes the script more spaced out.) however, this still remains as preference to the scripter.

    The following example is good:
    PHP Code:
    function onCreated()
    {
      
    this.chat "Hello";
    }

    function 
    onPlayerChats()
    {
      
    this.chat "WHAT DO YOU MEAN";

    The following example is bad:
    PHP Code:
    function onCreated() {
      
    this.chat "Hello";
    }
    function 
    onPlayerChats()
    {
      
    this.chat "WHAT DO YOU MEAN";

  • B.2.4. Topic Separation

    Topic separation has two parts.

    B.2.4.1. Keeping code dedicated to one purpose
    If you are writing code that performs several tasks, i.e. drawing an image and then writing to some player variables, these should be seperated by a blank line.

    The following example is good:
    PHP Code:
    //#CLIENTSIDE
    function onCreated()
    {
      
    showimg(200"testimage.png"100100);
      
    changeimgvis(2004);

      if (
    player.30)
      {
      }

    And the following example is bad:
    PHP Code:
    //#CLIENTSIDE
    function onCreated()
    {
      
    showimg(200"testimage.png"100100);
      
    changeimgvis(2004);
      if (
    player.30)
      {
      }

    B.2.4.2. Keeping conditional checks to a topic
    When using if () to check things, it is best that you keep all conditional checks to a set topic.

    The following example is good:
    PHP Code:
    function onCreated()
    {
      if (
    player.account == "Skyld")
      {
        if (
    player.30 && player.30)
        {
        }
      }

    And the following example is bad:
    PHP Code:
    function onCreated()
    {
      if (
    player.account == "Skyld" && player.30 && player.30)
      {
      }

  • B.2.5. Comments
    Keep the style of the comment suited to the length of the comment.

    For more than two lines of comments, you should use this:
    PHP Code:
    /*
      Comments.
      More comments.
      Even more comments.
      Rah rah rah.
     */ 
    For up to two lines of comments, you should use this:
    PHP Code:
    // Comments.
    // Further commenting. 

C. Code Efficiency Rules

These guidelines are simply designed to assist in making your code more efficient.
  • C.1. Do not use an event block more than once

    You should only use an event block once per script.

    This applies especially to old gscript.

    The following example is good:
    PHP Code:
    function onPlayerChats()
    {
      if (
    player.chat == "Hello")
      {
        
    this.chat "Good day to you, sir";
      }
        else
      if (
    player.chat == "Goodbye")
      {
        
    this.chat "Take care of yourself, sir";
      }

    The following example is bad:
    PHP Code:
    function onPlayerChats()
    {
      if (
    player.chat == "Hello")
      {
        
    chat "Good day to you, sir";
      }
    }

    // More code here

    function onPlayerChats()
    {
      if (
    player.chat == "Goodbye")
      {
        
    this.chat "Take care of yourself, sir";
      }

  • C.2. Use arrays for values of one topic

    It is bad organisation and general bad practise to use more than one variable to store more than one value that are all related.

    The following example is good:
    PHP Code:
    function onCreated()
    {
      
    this.myaccount player.account;
      
    this.myposition = {player.xplayer.yplayer.level.name};

    And the following example is bad:
    PHP Code:
    function onCreated()
    {
      
    this.myaccount player.account;
      
    this.myx player.x;
      
    this.myy player.y;
      
    this.mylevel player.level.name;

  • C.3. Don't put //#CLIENTSIDE in unusual places such as inside code blocks

    This isn't really an efficiency rule as such - it's a fundamental requirement - that //#CLIENTSIDE should not be put inside a function or such.

    This means, that //#CLIENTSIDE should always be outside of a code block.

    The following example is good:
    PHP Code:
    function onPlayerChats()
    {
      
    this.chat player.chat;
    }

    //#CLIENTSIDE

    function onCreated()
    {
      
    showimg(200"testimage.png"100100);
      
    changeimgvis(2004);

    And the following example is bad:
    PHP Code:
    function onPlayerChats()
    {
      
    this.chat player.chat;
    }

    function 
    onCreated()
    {
      
    //#CLIENTSIDE
      
    showimg(200"testimage.png"100100);
      
    changeimgvis(2004);

  • C.4. Don't put code outside of an event block

    Code should always be inside an event block, so that code execution is, well, organised. Putting code outside of an event block is a Generally Bad Idea™. The only exception to this is a use of this.join();.

    The following example is good:
    PHP Code:
    function onCreated()
    {
      
    this.chat "Welcome";

    And the following example is bad:
    PHP Code:
    this.chat "Welcome"

End. Suggestions and constructive criticism welcome.
__________________
Skyld

Last edited by Skyld; 05-11-2007 at 04:51 PM.. Reason: Updating the document
Reply With Quote
  #2  
Old 10-18-2005, 05:42 PM
ApothiX ApothiX is offline
Okiesmokie
Join Date: May 2004
Posts: 1,447
ApothiX is on a distinguished road
So you've made your own "SSI-GS2"?

Quote:
Originally Posted by Skyld
The following example is bad:
NPC Code:

function onCreated() {
chat = "Hello";
}

What is wrong with that style? :|
__________________


[06:24:19] * Parts: Skyld ([email protected]/skyld) ("Perhaps Okiesmokie did not realise that I like the boys. ")
Reply With Quote
  #3  
Old 10-18-2005, 05:46 PM
Skyld Skyld is offline
Script-fu
Skyld's Avatar
Join Date: Jan 2002
Location: United Kingdom
Posts: 3,914
Skyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud ofSkyld has much to be proud of
Send a message via AIM to Skyld
Quote:
Originally Posted by ApothiX
So you've made your own "SSI-GS2"?
If you want to call it that.
Quote:
Originally Posted by ApothiX
What is wrong with that style? :|
Quote:
Originally Posted by Skyld
Imagine that you have a long script with a lot of braces being used. Reading over it with braces on their own lines not only makes it easier to spot where blocks are opened and closed, but it makes the script more spaced out.
I find it much easier to read over code that has braces on their own lines for those reasons. I am sure that others would agree with me.
__________________
Skyld
Reply With Quote
  #4  
Old 10-18-2005, 05:56 PM
ApothiX ApothiX is offline
Okiesmokie
Join Date: May 2004
Posts: 1,447
ApothiX is on a distinguished road
Ack, sorry, just quickly skimmed through it and didn't notice the explanation.

Quote:
Originally Posted by Skyld
I find it much easier to read over code that has braces on their own lines for those reasons. I am sure that others would agree with me.
I guess it's just a matter of getting used to it. Personally, I don't like seeing so many irrelevant lines, and things are easier to follow with they are in the form:

a() {
}

It's probably because I use that style in both gscript and c, and have been using it for quite some time :x
__________________


[06:24:19] * Parts: Skyld ([email protected]/skyld) ("Perhaps Okiesmokie did not realise that I like the boys. ")
Reply With Quote
  #5  
Old 10-18-2005, 06:47 PM
Polo Polo is offline
Classic Systems Admin
Join Date: Sep 2002
Location: Vancouver, Canada
Posts: 735
Polo is on a distinguished road
Send a message via AIM to Polo
I agree with ApothiX on this one, in the sense that I prefer packing the opening brace at the END of the leading line. HOWEVER, I agree that both are perfectly valid, and you will find most scripters are 50/50 split as to which is better. As a result I think both should be allowed as valid in the guidelines above.

Edit:
I spoke with Skyld and this issue is now changed. See above (Section 2.3) for the new proposal. As it currently stands, I am agreeing with everything proposed, so Skyld currently has my endorsement .
__________________
Be good little players, or Master Storm will ban you!



Proof that the staff are crazy..
*Ghost Pirate: I'm a little teacup short and stubbe here is my raygun here is my butt
DragonX: Jumping jack rabbits Batman! Our eggo waffles have been stolen! To the batmobile Robin!
X-Mann (RC): I have a head ache

Last edited by Polo; 10-18-2005 at 07:15 PM..
Reply With Quote
  #6  
Old 10-18-2005, 09:23 PM
excaliber7388 excaliber7388 is offline
Banned
excaliber7388's Avatar
Join Date: Jul 2005
Location: US
Posts: 5,229
excaliber7388 can only hope to improve
Send a message via AIM to excaliber7388
WHY IS EVERY ONE LOOKING AT ME?
XD I'll do my best from now on, thanks!
Reply With Quote
  #7  
Old 10-18-2005, 09:57 PM
ApothiX ApothiX is offline
Okiesmokie
Join Date: May 2004
Posts: 1,447
ApothiX is on a distinguished road
Ah, with that edit, I'll have to agree aswell that Skyld's guidelines are suitable
__________________


[06:24:19] * Parts: Skyld ([email protected]/skyld) ("Perhaps Okiesmokie did not realise that I like the boys. ")
Reply With Quote
  #8  
Old 10-18-2005, 10:47 PM
napo_p2p napo_p2p is offline
oh snaps
napo_p2p's Avatar
Join Date: Sep 2003
Location: Pismo Beach, California
Posts: 2,118
napo_p2p has a spectacular aura aboutnapo_p2p has a spectacular aura about
Send a message via AIM to napo_p2p Send a message via MSN to napo_p2p
Quote:
Originally Posted by ApothiX
Ah, with that edit, I'll have to agree aswell that Skyld's guidelines are suitable
Ditto .
__________________
Scito hoc super omnia.
Haec vita est tua una sola.
Dum vita superest, utere maxime quoque puncto, momento, et hora quae habes.
Tempus neminem non manet.
Noli manere tempus.
Carpe Diem

Seize the Day.
Reply With Quote
  #9  
Old 10-18-2005, 11:40 PM
Silent Silent is offline
<3
Silent's Avatar
Join Date: Mar 2005
Location: England
Posts: 132
Silent is on a distinguished road
Send a message via AIM to Silent Send a message via MSN to Silent
Very well explained and laid out, good job
__________________
Quote:
Originally Posted by MilkyWay0016
The Bible also says things like...

"Stone disobedient children" (Deuteronomy 21:18-21)
Quote:
Originally Posted by Loriel
Disobedient children are likely enough to get stoned already, I think.
Reply With Quote
  #10  
Old 10-19-2005, 03:32 AM
Riot Riot is offline
Delteria Management
Join Date: Nov 2003
Location: Seminole County, Florida
Posts: 280
Riot is on a distinguished road
It is certainly something I can agree to, however, you should mention the use of "else" and "else if" to remove unneeded conditional checks.
Reply With Quote
  #11  
Old 10-19-2005, 04:18 AM
ApothiX ApothiX is offline
Okiesmokie
Join Date: May 2004
Posts: 1,447
ApothiX is on a distinguished road
Quote:
Originally Posted by Riot
It is certainly something I can agree to, however, you should mention the use of "else" and "else if" to remove unneeded conditional checks.
But that will lead to bashing of my favourite style

NPC Code:
if(condition) {
statements;
} else {
statements;
}

__________________


[06:24:19] * Parts: Skyld ([email protected]/skyld) ("Perhaps Okiesmokie did not realise that I like the boys. ")
Reply With Quote
  #12  
Old 10-19-2005, 04:43 AM
prozac424242 prozac424242 is offline
Registered User
prozac424242's Avatar
Join Date: May 2001
Location: Gone crazy: back soon
Posts: 356
prozac424242 is on a distinguished road
Send a message via ICQ to prozac424242 Send a message via AIM to prozac424242
(hides from the obsessivly neat people) ... cleanliness is good, and scripting/programming should be visually appealing as an art form ... but there is a point where becoming insanely obsessive about whether or not there is one extra blank line separating code blocks deeming your code to be good or bad ... that sends certain folks running the other way ... folks like me who care about making it work first, then commenting it and making it look nice later.

I feel that comments are more important than how the code looks, becasue in the end few people are going to see your code - far more are going to see what actions your code performs. And if there are comments, then the next npc person who picks up your code can most likely figure out your code and will either re-format what you wrote to their liking, or simply redo what you made from scratch to perform the same function.
__________________

Useful links:
Graal Stats
Client Script Functions-GS1 to GS2
Serverside Script Functions-Gscript page
Particle Engine-Player Attributes
Server Options-Admin rights-Gmaps
Quote:
Originally Posted by Admins
Thanks for developing and improving playerworlds and such
Reply With Quote
  #13  
Old 10-19-2005, 04:48 AM
napo_p2p napo_p2p is offline
oh snaps
napo_p2p's Avatar
Join Date: Sep 2003
Location: Pismo Beach, California
Posts: 2,118
napo_p2p has a spectacular aura aboutnapo_p2p has a spectacular aura about
Send a message via AIM to napo_p2p Send a message via MSN to napo_p2p
Quote:
Originally Posted by prozac424242
I feel that comments are more important than how the code looks, becasue in the end few people are going to see your code - far more are going to see what actions your code performs. And if there are comments, then the next npc person who picks up your code can most likely figure out your code and will either re-format what you wrote to their liking, or simply redo what you made from scratch to perform the same function.
For me, style > commenting.

I'd rather work on a nicely styled script that isn't commented, then work on a commented script that is all on one line.
__________________
Scito hoc super omnia.
Haec vita est tua una sola.
Dum vita superest, utere maxime quoque puncto, momento, et hora quae habes.
Tempus neminem non manet.
Noli manere tempus.
Carpe Diem

Seize the Day.
Reply With Quote
  #14  
Old 10-19-2005, 02:48 PM
ApothiX ApothiX is offline
Okiesmokie
Join Date: May 2004
Posts: 1,447
ApothiX is on a distinguished road
Quote:
Originally Posted by prozac424242
folks like me who care about making it work first, then commenting it and making it look nice later.
Believe it or not, when code looks nice, and is easy to read, it makes debugging go a lot smoother. If I had an error in a code that was very poorly formatted, it would take me a long time to find where the error was, but if everything was formatted correctly, it is much easier to spot errors and correct them.
__________________


[06:24:19] * Parts: Skyld ([email protected]/skyld) ("Perhaps Okiesmokie did not realise that I like the boys. ")
Reply With Quote
  #15  
Old 10-19-2005, 06:21 PM
prozac424242 prozac424242 is offline
Registered User
prozac424242's Avatar
Join Date: May 2001
Location: Gone crazy: back soon
Posts: 356
prozac424242 is on a distinguished road
Send a message via ICQ to prozac424242 Send a message via AIM to prozac424242
I do agree that having your own format
of code that works for you is something every programmer will develop.
I have more than 20 years of programming under my belt,
and when I write any program there is an order to it,
each command and bracket gets its own line, I indent nested blocks of code,
but I do it all as naturally as breathing.
I don't need to think about it, I just do it.
But I don't need to write a lengthly document explaining how I do it,
since everyone who sticks with programming of any kind will pick it up anyways to save their own sanity when they go back to edit their old code.
__________________

Useful links:
Graal Stats
Client Script Functions-GS1 to GS2
Serverside Script Functions-Gscript page
Particle Engine-Player Attributes
Server Options-Admin rights-Gmaps
Quote:
Originally Posted by Admins
Thanks for developing and improving playerworlds and such
Reply With Quote
Reply

Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are GMT +2. The time now is 01:01 AM.


Powered by vBulletin® Version 3.8.11
Copyright ©2000 - 2022, vBulletin Solutions Inc.
Copyright (C) 1998-2019 Toonslab All Rights Reserved.