Program style and readability

Any experienced assembler language programmer reading this chapter will probably be thinking by now, 'What a load of rubbish.' The examples presented so far are not, it must be admitted, models of clarity and elegance. This was deliberate; it gives us a chance to point out how they are deficient and how these deficiencies may be remedied.

As we learned in Chapter One, assembly language is about as far from the ideal as a normal human programmer is likely to venture. When writing an assembly language program, you should therefore give your reader as much help as possible in

understanding what is going on. Bear in mind that the reader may well be you, so it's not just a question of helping others.

Comments are the first line of attack. As we have seen, comments may appear as the first (and only) thing on the line, or after the label, or after the label and instruction. A

comment may not come between the label and instruction, as the instruction will be ignored, being taken as part of the comment. We have used ; to introduce comments, as this is the same character that many other assemblers use. The BBC BASIC assembler also allows you to use \ and REM. Whatever you use, you should be consistent.

A comment should be meaningful. The comments at the start of a routine should explain what it does, what the entry and exit conditions are, and what the side-effects are. Entry and exit conditions usually pertain to the contents of the ARM registers when the routine is called and when it returns, but may also include the state of specific memory locations at these points too.

The side-effects of a routine are similar to saying what it does, but are more concerned with actions which might affect the operation of other routines. A common side-effect is that of corrupting certain registers. Another example might be a routine which prints a character on the screen as its main action, but corrupts a pointer in RAM as a side-effect. By documenting these things in comments, you make it much easier to track down bugs, and to interface your routines to each other.

From the remarks above, it can be seen that the routines presented above are poorly served with comments, and this makes it more difficult to understand them, even though they are quite short.

Another important way of increasing readability is to use names instead of numbers. Examples where this clouded the issue in earlier programs are:

80 CMP R0,#126

2040 SWI 4 ;Read a char

Admittedly the second example has a comment which gives the reader some idea, but the first one is totally meaningless to many people. In the BBC BASIC assembler, wherever a number is required in an operand, the full power of the BASIC expression evaluator is available. The most obvious way to utilise this is to use variables as names for 'magic' numbers. For example, in the character program, we could have included an assignment 17 maxChar = ASC"~"

and made line 80: 80 CMP R0, #maxChar

In the first place we are told in line 17 what the last character to be printed is, and secondly the name maxChar gives a much better indication in line 80 of what we are comparing. In the second example, the operand to SWI was a code number telling the operating system what routine was desired. This was the read character routine which goes by the name of ReadC. So the program can be made more readable by adding the line:

1005 ReadC = 4 : REM SWI to read a char into R0

and changing line 2040 to: 2040 SWI ReadC

which makes the comment redundant. The SWI 256 is another instruction that can be improved. This particular SWI has an operand of the form 256+ch, where ch is the code of

character to be printed. It is given the name WriteI (for write immediate) in Acorn documentation, so we could have an assignment like this:

1007 WriteI=&100 : REM SWI to write char in LSB of operand

and change the instructions to have the form: 2070 SWI WriteI+ASC"O"

The importance of giving names to things like SWI codes and immediate operands cannot be understated. A similarly useful tool is naming registers. So far we have used the denotations R0, R1 etc. to stand for registers. In addition to these standard names, the assembler accepts an expression which evaluates to a register number. An obvious application of this is to give names to important registers such as the SP by assigning the appropriate register number to a variable. For example, if we had these three assignments in the BASIC part of a program:

10 link = 14 : REM BL link register

20 sp = 13 : REM My stack pointer register 30 acc = 5 : REM Accumulator for results

then instructions could take the form: 1000 MOVCS pc,link ;Return if too big

1210 STM (sp)!,{acc,link} ;Save result and return addr

2300 LDM (sp)!,{acc,pc} ;Return and restore

There are two things to note about these examples. The first is that we use the name pc even though this wan't one of the variables we defined above. The BASIC assembler recognises it automatically and substitutes R15. The second is that sp has brackets around it. These are required because the ! sign is used by BASIC to denote 'indirection'. To stop BASIC from getting confused you have to put brackets around any variable name used before a ! in STM and LDM instructions. You don't need the brackets if a register name, such as R13, is used.

In the examples in this book, we use the names pc, link and sp as shown above, and we also use names for other registers where possible. There is no confusion between register numbers and immediate operands, of course, because the latter are preceded by a # sign. So:

4310 MOV acc,sp

4310 MOV acc,#sp

would load the immediate value 13 into the acc register.

The final point about style concerns layout. The assembler doesn't impose too many constraints on the way in which you lay out the program. As we have already mentioned, labels must come immediately after the line number, and comments must appear as the last (and possibly only) thing on the line. However, it is advisable to line up the columns where possible. This makes it easier to follows comments if nothing else. Comments describing individual routines or the whole program can be placed at the start of the line. This also applies to comments for instructions which wouldn't fit on the line easily (e.g. after an STR with a long register list).

Line spacing can also be important. It is a good idea to leave blank lines between routines to separate them.

A typical format would be: ten spaces for the label, 25 for the instruction, and the rest of the line for the comment. For example:

1230 MOV count, #15 ;Init the counter

1240.loop SWI writeI+ASC"*" ;Print an asterisk 1250 SUB count, #1 ;Next count

1260 BNE loop

Another minor point of style in the listing above is the spacing of operands. It is easier to separate operands if there is at least one space character between them.

By way of a simple contrast, we list the very first program of this chapter, trying to practise that which we have just been preaching.

10 DIM org 40 20 P% = org

30 outReg = 0 : REM Register use by WriteC. Preserved 40 link = 14 : REM BL link register

50 pc = 15 : REM ARM program counter

60 WriteC = 0 : REM SWI code to print char in R0 70 firstChar = ASC" "

80 lastChar = ASC"~" 90 [

100 ;A simple ARM program. This prints the ASCII 110 ;character set from 'firstChar' to 'lastChar' 120 MOV outReg, #firstChar ;Init the output char 130.loop

140 SWI WriteC ;Display the char.

150 ADD outReg, outReg, #1 ;Increment the character 160 CMP outReg, #lastChar ;Finished?

170 BNE loop ;No so loop 180 MOV pc, link ;else return 190 ]

Because the line numbers are not particularly relevant to the assembly language, listings in subsequent chapters don't use them.

Finally, a note on cases. The assembler is totally case-insensitive. Mnemonics and 'R's in R0 etc. may be in upper or lower case or any combination thereof. Labels, however, must obey the rules of the rest of BASIC, which state that variable names are case dependent. Thus LOOP is a different label from loop, and Loop is again different. The convention used in this book is upper case for mnemonics and R0-type designations, and a mixture of upper and lower case (e.g. strPtr) for labels and other names. As usual, the method you adopt is up to you, consistency being the important thing.