Script Style Guide

There are no absolute rules which define the layout of scripts. Any style which suits the individual and which satisfies the script syntax rules may be used. The style proposed here, as used in the Mailtraq User Guide, is not mandatory therefore, but should prove to be of considerable benefit not just because it promotes clarity and legibility but also because it enables better use to be made of the many script examples which have already been placed in the public domain. Consider the following script:-

msg_txt:=openfile("message.txt");postmessage("postmaster","johns",
while(not(eof(msg_txt)),read(msg_txt)++"\n"));closefile(msg_txt)

That script consists of three expressions delimited by semicolons. It is syntactically correct and is interpreted correctly by Mailtraq. Excellent it may be as an exercise in obfuscation but it is not only difficult to read but also difficult to debug if errors are encountered. This script style guide attempts to explain how that sample script can be rewritten to make its structure and purpose clear to the user by following a simple set of rules.

Functions
Show Mailtraq functions in proper case (with a leading capital letter) and with each element of the function name also in proper case. For example, msggetlinecount() is a legal function but is better written as MsgGetLineCount() which enables the eye to parse the function name for its constituent parts more readily and also helps to distinguish functions from other elements of the script language. The commas which separate the individual arguments of each function should be used in exactly the same way as in normal English, with no preceding space and one trailing space.

Variables
Two conventions are employed for variable names in this help file. Firstly, they always appear in lower case; secondly, they include an underscore in their name wherever practical. It is also often helpful if meaningful names are used, either in the descriptive style of "msg_txt" used in the above example or, when opening a series of files, by employing sequential variable names, "a", "b", "c", etc., in the order in which the files are opened. This provides a simple mnemonic to ensure that all open files are explicitly closed.

Operators
For best effect, operators ("+", "/", etc.) should be separated from surrounding elements by leading and trailing whitespace and should be grouped using brackets when calculation precedence must be observed.

Script Layout
Although scripts are written to be interpreted by computers they must also be maintained by humans. The primary considerations for script layout, therefore, are line length and clarity of purpose. In addition, there are simple rules which can be observed to ensure that dependencies within functions, that is when the result of one function depends on the result of another function, are easily recognised. Here's another variation on the same script:-

msg_txt := OpenFile("message.txt");
PostMessage("postmaster", "johns", While(Not(EOF(msg_txt)), Read(msg_txt) ++ "\n"));
CloseFile(msg_txt)

The three major expressions within the script are now shown on separate lines (broken at the ";" expression separator). Lines one and three can now be easily understood but line two contains too much nested information to make its purpose clear and may also be too long for comfortable reading on some systems. The PostMesssage() function takes three parameters and the natural breaks provided by these can be utilised to good effect:-

msg_txt := OpenFile("message.txt");
PostMessage("postmaster", "johns",
  While(Not(EOF(msg_txt)), Read(msg_txt) ++ "\n")
);
CloseFile(msg_txt)

Three items of note. First, the closing right bracket of the PostMesssage() function now appears on its own line at the end of that expression and is aligned in the same column as the start of the PostMesssage() function to better indicate ownership. Second, the first two parameters to the PostMessage() function remain on the first line because they can easily be accommodated. Third, the third parameter is indented from the start column of the PostMesssage() function by two spaces to indicate dependency.

The third parameter to the PostMesssage() function contains a While() loop which is not excessively long in this example but it may also usefully be written on multiple lines to better indicate the scope of the While() loop and to add clarity to the script:-

msg_txt := OpenFile("message.txt");
PostMessage("postmaster", "johns",
  While(Not(EOF(msg_txt)),
    Read(msg_txt) ++ "\n"
  )
);
CloseFile(msg_txt)

Note how the closing bracket of the While() function is again aligned directly under the start of its function name and that the second parameter of the While() loop is also indented to indicate its dependency. It is now possible to debug the syntax of that script more easily, to spot missing brackets, for example, and it can be read, and its purpose understood, with a minimum of effort.