r1 - Tutor's Ramble 1 - About Source Code Layout


r1.1 - Why worry about layout ?

Before we go on to learn more about Alan, a few hints about the layout of source code files might be useful.

The aim of laying out source code in a tidy way is to make it easier for humans to read. The simple clear syntax of the Alan language leads naturally to more readable source code than many other languages but it still pays to write neat and tidy Alan source code.

r1.2 - Remarks

The most important element of readable source code is to add comments to the source code to perhaps describe why things are done a certain way and so on. Even if you wrote it yourself, source code can look very unusual even a few days let alone years after you first wrote it. Remarks in Alan are lines of text starting with two hyphen symbols. The Alan compiler ignores any text on a line after two hyphen characters and doesn't attempt to compile it. For example the compiler would ignore these lines of source code:

-- T1.ala
-- First Example of an 'Alan' Adventure
-- Feb 96 

r1.3 - Spacing

The spacing between lines of code and between words is insignificant to the Alan compiler. Alan uses a full stop (or 'period') character to denote the end of all statements. You can, therefore, lay out the source code any way you like as long as you remember the full stop characters and that there is atleast one space between words.

It is a good idea to separate sections of code with blank lines so it is easy to see what code relates, say, to one location.

This piece of source code ....

and this piece ....

are exactly the same to the Alan compiler but the second layout is much easier for human readers!

r1.4 - Capitilisation

I've used a convention in the examples with this tutorial of typing Alan 'keywords' like location, syntax, end and verb in uppercase letters. It looks a little ugly but distinguishes the components of the Alan language from the writer's own item names and descriptive text. In the following example 'exit' and 'to' are Alan keywords:

r1.4.1 - Capitilisation (its not significant....)

Note that the case of letters is of no significance to the Alan compiler - EXIT and exit mean the same thing; ItsAPlace and itsaplace are the same location. The capitilisation is solely for the benefit of readability.

r1.4.2 - Capitilisation (....except where its very significant!)

On the other hand, note that capitilisation is significant in text placed in single-quotes - for example in the syntax for the 'quit' command.

You should always write syntax in lower case because of the combined effect of two facts. Firstly, text in quote-marks is stored by the Alan compiler exactly as the game author typed it with the captilisation retained. Secondly, the Arun game-player program converts all player input to lower case before it analyses the input to figure out what the player means.

Remember that the text on the right of the equals sign in a SYNTAX statement specifies what a player can input. If we had specified the quit syntax to be, for example,

the user would be unable to enter the command as we would have specified that the player must type Quit with an upper-case Q and there is no way for the player, no matter what case they type their input on the keyboard, to actually enter an upper-case Q into Arun.

r1.5 - Indentation

It is a good idea to indent the lines of code between the first and last lines of a section to visually separate that section. Indentation is particularly helpful when reading more complicated blocks of source code than we have looked at so far. A good example would be if-then-else statements which are described in a later lesson.


Table of Contents | Next Lesson