Aerospace Software Ltd.

Objective Real-Time Software on the ADSP21XX

Introduction to Objectivity

Structured Design

The antithesis of spaghetti code, is object oriented design. (Ha! I've used the word, now Booch et all will be happy!). This boils down to two very important tenets that were coined years ago, when the Three Amigos were still reading comic books:

Information Hiding and
Minimal Coupling.

Information Hiding can be achieved through Modularity and Minimal Coupling can be achieved with the use of Structured Definitions and Procedure Calls.

Programmer's Rule 1:

Maximize Information Hiding

Minimize Coupling

Fine, but what good is this, you may ask and how does one do structured design in assembler code?

The answer to the first question may be surprizing: Structured design reduces the size of the code and reduces the amount of typing you have to do, thereby minimizing errors and improving maintainability.

The answer to the second question may seem equally strange: You do structured design in assembler code exactly the same way as in a high level language, through the use of parameterised procedure calls, and structured arrays of variables.

Now, why is object oriented code created on a PC with a compiler such as Visual C++ (Microsoft Corporation) so huge and slow in comparison with flat C programs? Simple: Bad design, bad object libraries and unnecessary functionality, causes code bloat. It is not the paradigm that is at fault and I'll go ahead and prove it to you in the following pages.

Your Golden Rule to reducing writer's cramp, also known as repetitive strain injury (RSI) or Karpal Tunnel Syndrome, should be to always strive to define something once and only once.

Programmer's Rule 2:

Always strive to define something once and only once.

This may seem obvious, but look at a typical spaghetti code project: Assume that Mr H.Acker is responsible for the DSP code of a 4 channel data recorder. Since he has no inkling how the hardware works and he does not want to write a programmer's reference document, he experiments with one channel until he gets it to work. Wheee! It works!

Now H.Acker has a long and winding piece of code which reads the data on one channel. In order to handle 4 channels, H.Acker simply grabs his favourite editor (Usually VI, no offence...) and cuts and pastes the code string 3 times, below each other, then he goes back up in the file and changes all the variables and labels to something like channel_a, channel_b etc. up to channel_d. That's it, quick and easy, quite neat too, since one can see exactly where each channel is handled in the code. H.Acker is really proud of himself, a job well done.

So what is the problem with this aproach? Well, six months later, the hardware designer releases his brand new, super duper, 32 channel data recorder. Now what!? If H.Acker would make another series of block copies of his code, he is sure to run out of memory, on a typical small embedded system and even if he could, imagine taking care of the small changes in the hardware design, which now need to be replicated 32 times in the code. Ugh! This is usually the point where H.Acker resigns and goes to work at another company. (Actually, this is not funny, I've seen things like this, it is quite common!).

The other problem is that of reliability. A bug always resides in something that was not tested. Now, Mr H.Acker above, increased his testing and debugging load 4 times, by copying his code 4 times. I bet he thought that since it works on one channel, the other three must work without testing. Welcome to real life, spelling mistakes, cats running over the keyboard etc.

Hacker's Dilemma 1:

If you duplicate code, you increase your work load and decrease quality.

So, what should H.Acker have done? He should have defined a channel of the recorder as an object (Oops, there I go again), I'm sorry, I mean data structure! If he defined all required variables in arrays, then he could have addressed all variables via array pointers and he would have needed only one code fragment for all 4 channels. Then, when the new 32 channel hardware arrived, all he would have needed to do, would have been to increase the maximum array depth from 4 to 32 and rebuild the code!

Programmer's Dilemma 1:

Test everything.

Bugs reside in code that was not tested.

Hello!? If you have four channels, that run at the same time, how can you have only one piece of code to control them? Bear in mind that the computer can only do one thing at a time anyway, so even if you had 4 independent code execution threads, the processor will only execute one at a time. Therefore, you only need one thread, with 4 sets of data variables. If you define these variables in a 4 dimensional array, then the same code thread can handle all 4 channels and you then have to debug the code only once, which is a big boon, as defined in Programmer's Rule 2. Furthermore, you reduce the amount of code memory required by a factor of 4, when compared to the spaghetti code of H.Acker.

Look-up Tables

An important mechanism to achieve structured code, is the use of look-up tables. In fact, perfect code consists of a single look-up table. It has no code, nothing to debug and is simply perfect.

Programmer's Dilemma 2:

Perfect code consists of a single look-up table, which is impossible.

Unfortunately, every look-up table requires a mechanism to perform the look-ups, but if you do things wisely, the structure of all look-up tables in your project will be the same and you'll have a single look-up procedure to debug.

Coding Standards

Structured design requires discipline. The required discipline should be mapped out in a coding standard. A strict coding standard reduces bugs and speeds up testing. How? you may ask. Let's go back to the spaghetti code of Mr H.Acker.

Programmer's Rule 3:

Adherence to a strict coding standard reduces bugs and speeds up testing.

H.Acker heard about modules and he knows that if he has one huge source file, it takes forever to assemble. Therefore, he did use a handful of source files, which are loosely structured around physical functionality (See, even hackers use objects!). In file main.dsp (Gee, what an inventive name), he defined a variable called BitCounter, to count the data bits streaming into the serial port of channel a. This was good and fine, until he duplicated the code and had to change it to BitCounterA through BitCounterD. However, his recorder had to talk to a computer to dump all the data to a hard disk and had another serial port, where he also defined a BitCounter in file computer.dsp. This worked fine, until he added a debug port and renamed the counters BitCounterA and BitCounterB.

The linker will link the code perfectly, since these variables are defined in different files, but imagine what happens when he runs a simulator or in circuit emulator to debug the code. When he tries to display BitCounterC or BitCounterD, there is no problem, but when he types a command and refers to BitCounterA or BitCounterB, the debugger balks. To display these, he has to type the filename as well as the variable name, to show the debugger which variable he is referring to. All this typing eventually leads to a severe case of Karpal Tunnel Syndrome, H.Acker goes on indefinite sick leave, sues the keyboard manufacturer for compensation and another person has to finish the project.

Mr S.Ucker is a new hire, looks at the code of H.Acker, sees BitCounterA used all over the place and naturally assumes that it is one and the same variable, until he finally figures out three days later, that there are two variables called BitCounterA. Eventually S.Ucker performs text searches with a powerful text search utility, on each and every variable over all the files, in order to find out what belongs where, a task that keeps him sweating for 14 days.

Hackers everywhere use names such as count, state, length and error all the time and must have super human photographic memories to remember what is defined where. The obvious solution to this problem is a proper naming standard, which ensures that all definitions are unique and can be traced directly to the module in which they were defined, without having to grab the grep.exe utility. (Inheritance and polymorphism of object oriented languages create debugging nightmares. These features make the code unreadable and confusing. The inventors of polymorphism should be charged with crimes against humanity...).

Programmer's Rule 4:

Every definition must be unique and directly traceable to the module in which it was defined.

The next problem facing S.Ucker is the use of varying case in the definitions. It is bad enough to remember a name like ThisISaVeryLongAnd_DescriptiveNameA without having to remember which characters are capitalized or where exactly the underscore is hiding. This problem is best resolved using the guidelines of Kernigan and Ritchie, who started this case sensitive business (and who deserve to be clobbered with a baseball bat for it). They reduced it to to a simple case where literals, constants and type definitions are upper case, while everything else is lower case, using underscores for readability. Mixed case definitions are not allowed! It's a no, no and anybody propagating the use of mixed case deserves to be burned at a stake, since it is a major time waster...

Programmer's Rule 5:

Literals, constants and type definitions are upper case, while everything else is lower case, using underscores for readability.

To add to S.Ucker's woes, the debugger only displays the first 20 characters of a variable name, which reduces most of the variables to ThisISaVeryLongAnd_D making it well nigh impossible to debug the code, since he has to rely upon the order of the definitions to figure out what is what. Somehow H.Acker knew that the value he was interested in, was the third one from the top, or the fifth one from the bottom, but poor S.Ucker is completely lost.

Programmer's Rule 6:

Identifiers shall be unique, short and descriptive, in that order.

Finally, S.Ucker creates a master index of all definitions, writes a proper coding standard and spends another two weeks searching for and renaming all the definitions in all the code, by which time, he is convinced that he really should have rewritten it all, instead of trying to fix it.

The only problem being that since there is no software specification, he has to study the code to find out what the device is supposed to do...

Software Specification

Writing a software specification first, serves two purposes:

You'll get your thoughts organized.
You'll know when the project is completed.

Programmer's Rule 7:

Write a software specification before you start coding.

The fist item seems obvious, but few people think of the second one. If you are working for an ISO9001 company, you are required to do this anyway and it is sure to keep your boss happy, if you can show him which requirements have been coded and which have not. That provides a simple, measurable percentage completed indication and you'll score even more brownie points if you graph your progress.

There is also another good point to it. Every time your boss tells you about another nice thing he would like to see in the product, you can tell him that it is not in the specification and will add 2 weeks to your schedule! This effect is known as Requirements Creep and has been the death of many a project.

Programmer's Rule 8:

Manage Requirements Creep with a database or spreadsheet

A good way to handle requirements creep and software project management in general, is to enter all requirements as single line statements in a database or spreadsheet. Then you can tick them off as you go along and generate all your graphs and progress reports at the click of a button, thereby keeping your boss happy and smiling.