| Skyld |
10-18-2005 05:37 PM |
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", 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:
End. Suggestions and constructive criticism welcome. |
