6. Design Decisions

Documentation will be an integral part of the program, and will be done via my Document package. The documentation will be available in both HTML and PostScript form, via L^ATEX and L^ATEX2html.

Assume gmake is available. This allows many coding constructions not found in vendor makes, and increases portability.

``Design by Contract'' coding methodology will be used, but some terminology may be changed to be more meaningful.

For instance, ``assertions'' will be used, but will be referred to as ``verifications''. To ``assert'' means to state that something is true, whereas to ``verify'' means to test to make sure that something is true. Other nomenclature that I considered and rejected includes: check, confirm, certify, warrant, ascertain, ensure, guarantee. All of these are better than ``assert'', but I considered ``verify'' to be the best.

Also, ``invariant'' will be referred to as ``valid_state'', because it is more indicative of the test being done. Other nomenclature that I considered and rejected includes: self-consistent, consistent, well-formed, valid.

Granted, I may lose a small amount of understanding on the part of C programmers who are looking at my code (and are familiar with the terms ``assert'' and ``invariant''), but I will gain a great deal of understanding from people that are new to the ``Design by Contract'' method.

Assume gm4 is available. This means that line numbers from the source code can be output as error messages from the verifications.

Assume that all error line references are to the original, unprocessed files. This means that any header files can add blank lines, which means that the ubiquitous ``dnl'' can be eliminated, which will greatly increase readability.

In addition to the VERIFY macros, I'm making a WARN_IF macro that generates a warning if a test fails but continues program execution.

I considered using DejaGnu to automate testing, but ultimately rejected it. The reasons for rejection include:

It seems that DejaGnu's main thrust is testing on different platforms, and it requires Tcl and Expect to run. I don't want to require all three programs (Tcl, Expect and DejaGnu) to be able to test on other architectures.

It looks non-trivial to set up, especially since I don't know Tcl and Expect.

It's unclear what benefit, if any, would be derived from using it.

My current solution for testing, as far as modules are concerned, is to include a test routine at the end of each module which will only be activated if a gm4 flag is set. I'm including the "script" necessary to run each module test as Self-Documentation text that my perl script Document can pick out.