This article covers the basic ideas of structured programming, or some tips for writing better programs in Small Basic.

'Better' is subjective and people do prefer different styles, but there are some general rules that do help, especially when your programs get more complicated.

GoTo

This is the most controversial and opinion differs.

Normally a program runs one line, then the next, progressing through the code in a logical order.  It can do For or While loops and branch into different code using If, ElseIf and EndIf.  The path taken through the code is sometimes called the 'flow' of the code.  We want this flow to be as clear and logical as possible.

A GoTo just jumps somewhere completely different.  This can make the code very hard to follow and virtually impossible to debug or extend if they are used indiscriminately.  However, they are a very natural concept for the starting programmer before they know much about other ways to control the flow of code.

Below is a sample code using GoTo's too much - what is it supposed to do and why doesn't it work?

x = 0
y = 0
For i = 1 To 100
  a:
  x = x+1
  b:
  x = x-1
  c:
  If (i < 10) Then
    Goto a
  Else
    y = y+1
    Goto b
  EndIf
  If (y < 3) Then
    Goto c
  EndIf
EndFor
 
TextWindow.WriteLine(x+" "+y)

This example works fine, but is still very hard to follow.

Goto start
clear:
TextWindow.Pause()
TextWindow.Clear()
Goto Start
start:
count = 0
enterNumber:
TextWindow.WriteLine("Enter a number")
count = count+1
If (count = 1) Then
  num1 = TextWindow.ReadNumber()
ElseIf (count = 2) Then
  num2 = TextWindow.ReadNumber()
  Goto getOperation
EndIf
Goto enterNumber
getOperation:
TextWindow.WriteLine("Enter an operation (+,-,*,/)")
operation = Textwindow.Read()
If (operation <> "+" And operation <> "-" And operation <> "*" And operation <> "/") Then
  Goto getOperation
Else
  Goto dosum
EndIf
result:
TextWindow.WriteLine(num1+operation+num2+"="+result)
Goto clear
dosum:
If (operation = "+") Then
  result = num1 + num2
ElseIf (operation = "-") Then
  result = num1 - num2
ElseIf (operation = "/") Then
  result = num1 / num2
ElseIf (operation = "*") Then
  result = num1 * num2
EndIf
Goto result

These are called 'spaghetti' code.

The general rule is for every GoTo that you use, you should consider very carefully if there is a better way to do it - there almost always is.  There are occasions in Small Basic where it is the best option, but they are very rare.

You should never use a GoTo to jump into or out from a subroutine or your program will crash.  This is because the call stack will be corrupted.  The call stack is an internal structure that controls where a subroutine should return to when it ends and is updated when the subroutine is called and returned from.

Subroutines

Subroutines are pieces of code that perform a specific task.  Often the task may be needed in different parts of your code and prevent duplication of code.  If you are writing very similar code for different parts of your program, then probably subroutines could help.

A subroutine in Small Basic starts with the keyword Sub and ends with EndSub.  It can then be called by using the subroutine name followed by two round braces ().

value = Math.Pi
roundResult()
writeOutput()
 
Sub roundResult
  result = 0.001*(Math.Floor(1000*value+0.5))
EndSub
 
Sub writeOutput
  TextWindow.WriteLine("the current value rounded to 3 decimals is "+result)
EndSub

The subroutine code block can be placed anywhere in your code, but it is best to place them all together after you main code.

Often we can break a task into a number of sub tasks, each of which could then be a subroutine. 

The length of a subroutine is not that important, don't just subdivide a long piece of code into subroutines unless each has a specific task.  Generally it is good if the main or top-level subroutines are quite short so it is easy to follow the main logic of the program.

The key to subroutines is:

  • Making them do just one task - it may be very general like "Initialise Program" and include many sub tasks or be very specific like "Check overlap of 2 shapes".  You should be able to describe the subroutine task in just a few words and don't tempted to 'just add in a little something else'.
  • Make them as general as possible - especially if you might want to reuse the code in other programs.  See the section on "Variables or constants".

Comments

A comment in Small Basic starts with an apostrophe ' and is highlighted in green.  Anything after it is ignored to the end of the line.

'Calculate distance between objects
distance = Math.SquareRoot((x-a)*(x-a) + (y-b)*(y-b)) '(x,y) is the player

Comments are not just for others reading your code, they help remind you later why you did something.  More importantly they show the thinking behind the code and the ideas about how the program should work.

Try to add comments that explain something complex or why you did something one way or another.  They should remind you and help someone else understand the overall thinking you had when you wrote the program.

The 'more comments the better' is not good, the following comment adds nothing.

x = x+5 'Add 5 to x

Sometimes comments can be used to visually separate sections of your code like the start of subroutines.

'===================================================
'SUBROUTINES
'===================================================

Variable names

Try to use descriptive names for your variables, there is no penalty in performance or memory for long variable names.  Try not to make them too long, but be clear what they are.

There are conventions for variable naming, but most common is to mainly use lower case and capitalise each word apart from the first (that remains lower case).

For loop counters are usually just a single character, i, j, k etc.

playerTank = Shapes.AddImage(playerTankImage)
For i = 1 To numEnemy
  enemyTank[i] = Shapes.AddImage(enemyTankImage)
EndFor

Variables or constants

Sometimes in your code you use a value that is fixed, perhaps the number of enemies, or offset for positioning a shape at its centre or the text used to ask a question.

It is good practice to put all these constants in variables so that you can just change the variable without having to change the constant values throughout your code.  It can also make your code more general so that it can be re-used or subroutines used more extensively, reducing the need for duplicate code.  All the variables can be simply initialised in one subroutine at the start.

GraphicsWindow.Show()
displayText = "Hello World"
For i = 1 To 11
  letter = Text.GetSubText(displayText,i,1)
  letterShape = Shapes.AddText(letter)
  For j = 1 To 100
    Shapes.Move(letterShape,20*i,j)
    Program.Delay(10)
  EndFor
  Program.Delay(100)
EndFor)

The code above would be better written as below so we can easily change the parameters of the method if we change the font for example.

Initialise()
displayText = "Hello World"
ShowText()
 
Sub Initialise
  GraphicsWindow.Show()
  characterOffset = 20
  movingLetterSteps = 100
  delayMovingLetter = 10
  delayLetter = 100
EndSub
 
Sub ShowText
  For i = 1 To Text.GetLength(displayText)
    letter = Text.GetSubText(displayText,i,1)
    letterShape = Shapes.AddText(letter)
    For j = 1 To movingLetterSteps
      Shapes.Move(letterShape,characterOffset*i,j)
      Program.Delay(delayMovingLetter)
    EndFor
    Program.Delay(delayLetter)
  EndFor
EndSub

Arrays

Use arrays where possible to group items.  For example if you have multiple buttons, put them all in an array.  In the example below all we need to do to add more buttons is add a new buttonText array element.

Initialise()
Controls.ButtonClicked = OnButtonClicked
 
Sub Initialise
  buttonText[1] = "Clear"
  buttonText[2] = "Start"
  buttonText[3] = "Run"
  buttonText[4] = "Pause"
  buttonText[5] = "Exit"
  numButton = Array.GetItemCount(buttonText)
  
  For i = 1 To numButton
    button[i] = Controls.AddButton(buttonText[i],60*i-50,GraphicsWindow.Height-40)
    Controls.SetSize(button[i],50,30) 'Equal size to look better
  EndFor
EndSub
 
Sub OnButtonClicked
  lastButton = Controls.LastClickedButton
  For i = 1 To numButton
    If (lastButton = button[i]) Then
      GraphicsWindow.ShowMessage(buttonText[i]+" was clicked","Information")
    EndIf
  EndFor
EndSub

Code layout

Indentation and spacing

Use the indentation feature of Small Basic to format your code.  This can be found by right clicking and select 'Format Program'.

Also use blank lines to separate code segments, but try not to have lots of randomly placed blank lines.

Code order

Place your main code at the start, then place all subroutines below the main code, perhaps separating program subroutines and event subroutines.

Perhaps also separate your main code into sections like 'Initialisation and Setup', 'Main Program' or others that may apply.

Planning

Try to think of a program structure at the start, then create the main subroutines and variables/arrays and gradually add the detail.  Test detail in small prototype programs first, then add to the main program.

The temptation is to add all the fine detail of a program at the start and then build a structure around this, but this will often lead to code that is hard to develop and debug.