[futurebasic] TAN: avoid write-only assembler code

Message: < previous - next > : Reply : Subscribe : Cleanse
Home   : October 1999 : Group Archive : Group : All Groups

From: Zetalink Technology <zetalink@...>
Date: Fri, 22 Oct 1999 20:46:32 +0700
Sorry to post something that is a tangent topic, and might be of 
marginal interest, but a few days ago it was obliquely mentioned that 
assembler code is "write-only" -- or in other words, very hard to go 
back and read.

I happen to write a lot of assembler code for small microcontrollers 
such as the Motorola 68HC05. Some of the products have been 
frequently modified by customer requests over a five-year period. 
About six or seven years ago I began to write my comments in 
assembler that approach a high-level language, like a kind of 
pseudocode. This forms a parallel documentation "script" that allows 
one to go back later and easily read what was written. With this 
pseudocode, it is often quite easy to re-familiarize myself with what 
otherwise would be quite mysterious looking, cryptic code. In fact, I 
attempt to use structured indentation wherever it seems necessary to 
clarify the process. While it takes extra time, I feel it has it has 
paid off later when coming back to read it. I have also seen how it 
helps my assistants to understand my code, which is a testimonial to 
its efficacy.

Below I am including a small sample fragment. It is a sequence that 
tests bits and performs some bit re-mapping based on a two-bit device 
count (0-3). The bit-test branch conditionals are actually macros 
since the original machine operations require three operands (byte to 
test, bit number within the byte and the branch target address). My 
use of macros makes it easier to read by packing the bit number and 
byte address into a single assembler symbol, and the braset or braclr 
macro unpacks this symbol table entry. But the real point is that the 
comments, with some care to show indentation, make this a lot clearer 
to read.

Yes, it is tedious and takes time, but there are *still* places where 
assembler coding is needed due to very little memory codespace, such 
that even C compilers with multi-pass code optimization aren't yet 
good enough in squeezing things into a tiny chip.

The important thing is that no matter how cryptic a language is, 
there are ways to make it readable the next day and the next decade. 
While some programmers may be prolific and can write good code 
without such comments, their economy falls down when someday the code 
may need to be maintained. Then there is a price to pay.

The only thing missing in the below example is the presence of 
matching endif's. But the indentation implies its presence, easily 
verified by looking at the branch targets. I have found that doing 
this extra structuring helps me write better code and makes assembler 
programming more fun. It is even possible to write well-structured 
code much of the time.

;       z1 & z0 form two-bit binary count of valid devices
Rp12n   braset   z1,Rp13a      ;if device count = 1 or 2, then
         braclr   kc,Rp12p      ;. if code c
         bitclr   kc            ;. . remove code c bit
         bitset   ka            ;. . to make code a
Rp12p   braset   z0,Rp12r      ;. if device count = 1
         braclr   kb,Rp12q      ;. . if code b
         bitclr   kb            ;. . . remove code b bit
         bitset   ka            ;. . . to make code a
Rp12q   braclr   kd,Rp13a      ;. . if code d
         bitclr   kd            ;. . . remove code d bit
         bitset   ka            ;. . . to make code a
         bra      Rp13a         ;. else device count = 2, then...
Rp12r   braclr   kd,Rp13a      ;. . if code d
         bitclr   kd            ;. . . remove code d bit
         bitset   kb            ;. . . to make code b
Rp13a   lda      blue          ;next do something else

I have also programmed in another so-called write-only language, 
Forth, and I have found that the criticism of write-only is really 
just the ignorance of the critic who is unfamiliar with the language. 
If you don't know C but know Pascal, C is write-only. If you don't 
read Chinese, it is just so many seemingly random marks. The real 
test is if the person writing it, or another person equally familiar 
with the same dialect, can make sense of it at a later time.

BTW, for me, I have not been able to get past a certain elementary 
stage in writing AppleScript -- the problem for me is that the syntax 
seems too "loose", yet isn't smart enough to understand real English. 
I am still missing some
key "spark" that illuminates my aging brain and unlocks the mystery 
of it -- it seems murky and cloudy in a metaphorical sense. But I 
haven't spent much time with it, I admit.

Ray Weisling

BTW2, I "cut my teeth" in assembler in 1974-80 when I inherited 
maintenance of a Computer Automation minicomputer system whose unique 
application code was written with almost no comments (because it 
slowed down printouts on the ASR-33 teletype that poked along at 
incredible 10 char/sec). So the programmer just left everything 
uncommented. The pains I went through perhaps taught me the utter 
necessity of commenting anything that might be hard for another 
mortal human to follow. I eventually removed tons of bugs from that 
code, but it took me months to figure out how it worked.

  . . . . . . . . . . . . . . . . . .
  .  Zetalink Technology Indonesia  .
  .  Electronic Design Consulting   .
  .     & Cartographic Services     .
  .      Yogyakarta, Indonesia      .
  .    FAX 1-708-575-6950 (USA)     .
  .     zetalink@...        .
  . . . . . . . . . . . . . . . . . .