Texas Instruments TI-92+, Tip List

Page: 321 / 507

am counting on your program to give me a correct answer, I deserve some assurance that it really
works. In part, this assurance can come from knowing what algorithms you used to get the results. If
the calculation depends on some built-in function, for example, solve() or nint(), and you tell me that,
then I know that your program is limited by the performance of those functions, and I can evaluate the
results accordingly.
This section of the documentation can be fairly short. If I really want to know all the intricate details, I
can examine your source code. The real purpose of this section is to give an overview.
How can I change the program to better meet my needs?
It may be quite likely that your program almost does what the user wants. In this case, the user might
want to modify the program. To do this, she needs to understand how the program works, and this
means code documentation. Code documentation differs slightly from user documentation, because
both the intended audience and the purpose are different. User documentation meets the user's needs,
and the user is not necessarily a programmer. Code documentation meets the needs of a programmer.
Useful code documentation is actually a field of its own, and I'm only going to give a brief overview of
'best practices', based on my personal experience of programming and supervising programmers. The
documentation also interacts to a great degree with the underlying design of the code, which is a topic
that deserves a tip of its own.
A program consists essentially of data, calculations, and flow control. Because these three attributes
interact with each other, the documentation must specify the interaction, as well as the characteristics
of each of attribute. Data documentation consists of
!
Choosing a variable name. Ideally, variable names are long and descriptive. On the 89/92+,
memory is limited, so there is a strong motivation to keep variable names short, to save memory. In
any case, variable names are limited to eight characters, which often precludes truly descriptive
names. This means that descriptive documentation of variables is even more important. Some
simple conventions can help, as well. For example, integer loop counters are traditionally named
with integers i, j, k, l, m and n. Nested loops can use loop counters such as k1 and k2. Some
89/92+ programmers prefer to use Greek or non-english characters, especially for local variables.
Selecting variable names on the 89/92+ is further confounded by the fact that the AMS uses several
common, obvious names as system variables and data.
!
Describing the data type: is it a variable or a constant? Is it an integer, a string or a matrix? What
are the valid ranges and dimensions? What is the variable's physical significance? For example,
Vin1 and Vin2 may be two circuit input voltages, and Vout is the output voltage.
!
Clarifying variables which change type during the program execution. It is completely legal in TI
Basic to store a string to a variable which contains an integer, for example. While this improves
efficiency, it can make programs very difficult to understand. Further, it is common (and efficient) to
'reuse' a local variable when the previous contents are no longer needed.
Documenting calculations is fairly straightforward, particularly if the underlying data is well
documented. Keep in mind, though, that you want to describe the functional intent of the calculation,
not the calculation itself. For example, this isn't too helpful:
©Add 273. 1 5 to temp 1
temp 1 +273. 1 5 → temp 1
This is better:
7 - 32