SRL Archive - MSI Tutorials

As we will be scripting as a group, we need a standard to script by, so we can understand each other's code, keep it clean and simple. MSI uses the following standards, taken straight from THE Beginner's Simba Tutorial.

From: Coh3n

1. When you intent, it will be two spaces. You can do this by hitting the "Tab" button on your keyboard, or simply hitting the space bar twice.
2. Your script margins are set to 80 characters and is marked in Simba with a line straight down the right side of the scripting page. Try not to exceed that margin. If you do, no big deal, no one's going to kill you for it. ;)
3. The begin statement appears on its own line, and end statement always matches the begin statement by columns. For example:

begin
  if (Condition) then // Notice the intent after a "begin" statement
  begin // Notice how the begin lines up with "if" in columns
    DoThis;
  end else
  begin
    DoThis;
  end;
end;

Notice how all the begins and ends line up in columns. Also, you're probably wondering what the "if (Condition) then" is. Well, don't panic, it's called an if..then..else statement, and you'll learn more on that later. But, notice how the begin after the if statement is lined up with "if" in columns. Most people make the mistake of intending the "begin" after an if statement, which makes their code harder to read.
4. Use semicolons at the end of all your lines. Exceptions would be at the end of var, begin, then, else, repeat, do and before else (see the above example if you don't know what I mean).
5. Try not to combine two or more statements on one line. Each statement gets it's own line.

// Bad
if (Condition) then DoThis;
if (Condition) then begin DoThis; DoThat; end;

// Good
if (Condition) then
  DoThis;

if (Condition) then
begin
  DoThis;
  DoThat;
end; 

6. Always use spaces after commas and arithmetical signs. This is also a common mistake with most scripts, and it really bugs me when people don't do this. It makes the script much harder to read without the spaces. Here is an example:

// Bad
i:=(5*4+3);
HowManyLogs(1,5,10);

// Good
i := (5 * 4 + 3);
HowManyLogs(1, 5, 10); 

7. You should never have a white space on the inside of parenthesis. Example:

// Bad
if ( i = 100 ) or ( k = 50 ) then
  DoThis( DoThat );

// Good
if (i = 100) or (k = 50) then
  DoThis(DoThat);

8. Simba bolds keywords such as "begin, end, procedure, function, etc." These words should be entirely lowercase as it looks much better, and a lot of people find it easier to read. :)
9. The names of procedures and functions should always begin with a capital letter and be camel-capped for easier readability. Example:

// Bad
procedure walktobank;

// Good
procedure WalkToBank;

10. The names of procedures/functions/variables/constants should be given names meaningful to their content. A name like DoStuff is not meaningful, but name WalkToBank is. This includes a function's parameters.
11. The layout of programming components should be easily distinguishable between one another.
• Constants should be entirely uppercase.

LOGS_NORMAL = 0;
LOGS_OAK    = 1;

• Global variables should start with an uppercase letter and then camel-capped. This should also be the same for a function's/procedure's parameters (excluding single lettered parameters).

var
  TotalLogs: Integer;
  WhichTree: string;

• Local variables should start with a lowercase letter and then camel-capped.

procedure Example;
var
  i: Integer;
  tempString: string;
begin
end;

• Cases should be spaced out if necessary.

case anyVariable of
  VAR_EXAMPLE_1:
    begin
    end;

  VAR_EXAMPLE_2:
    begin
    end;

  VAR_EXAMPLE_3:
    begin
    end;
end;

// or if there's only one command per case

case anyVariable of
  VAR_EXAMPLE_1: command1();
  VAR_EXAMPLE_2: command2();
  VAR_EXAMPLE_3: command3();
end;

You may not like the look of some of these, so you don't have to use them. There are some programming languages out there that have forced standards. Thankfully, you don't have to worry about that as Pascal has no such thing.
12. Where possible, parameters/variables of the same type should be combined into one statement. For example:

// Bad
var
  Logs: Integer;
  Ores: Integer;
  Fish: Integer;

function WalkToBank(i: Integer; j: Integer; l: string; k: string): Boolean;

// Good
var
  Logs, Ores, Fish: Integer;
  
function WalkToBank(i, j: Integer; l, s: String): Boolean;

13. Boolean variable names must be descriptive enough so that their meanings of True and False values will be clear.

// Bad
var
  b: Boolean;

// Good
var
  DoesBank: Boolean

14. When you declare a variable, they are put on the next line after the var statement, and are indented. Example:

// Bad
var Logs: Integer;

// Good
var
  Logs: Integer;

15. Try to declare variables locally as much as possible to avoid confusion within the script.
16. The use of white space is highly suggested. It makes your code look neater, it's more readable, and in general I find it to be a good habit. Also, the readers of your script will appreciate it. If you don't know what I mean, don't worry, I'll be pointing out the use of white space as the tutorial goes on.

As well as those standards, MSI needs to be easy to understand. This comes with detailed commenting and documentation. Thanks to Wizzup? we have an awesome documentation site that automatically updates as our script and procedure headers update. View MSI's Documentation.

When you write code for MSI, you should use as much in-function commenting as possible so anything can understand why the writer did what they did. Each function/procedure also needs to include the following header. I'm sure you can figure out which parts need to be changed. ;)

(*
MSI_FindRandoms
~~~~~~~~~~~~~~~

.. code-block:: pascal

  procedure MSI_FindRandoms;

Checks to see if the player has encountered a random event

.. note::

  | Author: Coh3n
  | Last Updated: 07 December 2010 by Coh3n

Example:

.. code-block:: pascal

  if (not FindObjects) then // Note that FindObjects is used only as an example
    MSI_FindRandoms;
*)                         

Yes, some people may think it's long and ugly, but that's how we get our awesome documentation. :)

That's all you need to know!

Cheers,
The MSI Team

Please post all comments in original thread, here:
http://villavu.com/forum/showthread.php?t=56132

~RM

Reopened and stickied :)

Awesome. I'll add this to my list of tutorials to update. :) Most of it is the same, but I'll read it over and change what needs to be changed.

E: Updated! :)