Script Formatting Guidelines

[Skyld]

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", 100, 100);

  if (player.x > 30)
  {
    changeimgcolors(200, 1, 0, 0, 1);
  }
} 

  However, this example is bad:
  
  PHP Code:

  function onCreated()
{
showimg(200, "testimage.png", 100, 100);

if (player.x > 30)
{
    changeimgcolors(200, 1, 0, 0, 1);
}
} 

• 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(0, 0, "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", 100, 100);
  changeimgvis(200, 4);

  if (player.x > 30)
  {
  }
} 

  And the following example is bad:
  
  PHP Code:

  //#CLIENTSIDE
function onCreated()
{
  showimg(200, "testimage.png", 100, 100);
  changeimgvis(200, 4);
  if (player.x > 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.x > 30 && player.y > 30)
    {
    }
  }
} 

  And the following example is bad:
  
  PHP Code:

  function onCreated()
{
  if (player.account == "Skyld" && player.x > 30 && player.y > 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.x, player.y, player.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", 100, 100);
  changeimgvis(200, 4);
} 

  And the following example is bad:
  
  PHP Code:

  function onPlayerChats()
{
  this.chat = player.chat;
}

function onCreated()
{
  //#CLIENTSIDE
  showimg(200, "testimage.png", 100, 100);
  changeimgvis(200, 4);
} 

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