3.9 Conventions for Writing Programs

Individuals differ in their programming styles. A particular individual may use different styles when programming in different languages. The characteristics of a programming style include the following:

• the way you structure or subdivide a program;

• the algorithms you use to solve common problems;

• the instructions or language constructs you choose;

• the format and overall appearance of your source program; and

• the type of commenting that you incorporate in a program.

To be sure, bookshops and libraries contain books on programming style that offer methods to structure and format program source, as well as what language constructs to use or avoid. While not repeating such readily available information, we do wish to make a few general comments about assembly language programming.

Few complex programs are written entirely in assembly language. The exceptions are some critical systems programs and very importantly, we think those written for the purpose of learning about an architecture's instruction set. We strongly urge attention to the following goals:

1. The program must solve the problem at hand.

2. The program must clearly convey both the technique of solution and the details of implementation.

3. The program must be easy to understand and modify.

These goals require that the program contain good internal documentation. Choose common algorithms and instruction sequences, rather than arcane tricks.

Debugging will be facilitated by using quad words, or occasionally double words, to contain integer quantities. Although efficiency is admirable, computer memory is cheaper than human labor. Packing data into the smallest possible information units could require unreasonably long instruction sequences for unpacking and data manipulation.

Both in a learning context and in real-world program development, the comments become nearly as important to the program as the instructions. While comments are not executable, they are essential for a program to have a long and useful life, because they enable it to be understood and maintained.

In assembly language, virtually every line should have a meaningful comment. A comment that merely echoes the opcode and specifiers has no value, because a qualified reader already knows that information. A comment adds value when it explains why a particular instruction is used in a particular place. Comments on adjacent lines should work together to tell a story. Blocks of comment lines with no instructions can introduce a routine or separate a large effort into smaller units for better comprehension.

All of the sample programs in this book illustrate a style where comments, while quite concise, clearly convey the intent. This "less is more" approach allows the programs to be printed in portrait instead of landscape orientation on the pages of this book and also permits the programs to be displayed in a classroom setting from a projected computer display or transparency.