Programming Tips - Small Basic Featured Article

LitDev strikes again with another fantastic article on TechNet Wiki:

Small Basic: Programming Tips

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

 

Read the rest of the article (and the latest version) on TechNet Wiki:

Small Basic: Programming Tips

 

Thanks to LitDev for providing these great tips!

   - Ninja Ed