The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 10 : Programming Usage

PART 4 : USAGE

CHAPTER 10 : Programming Usage
10.1 Elegant programming
10.2 Performance programming
10.3 Defensive programming
10.4 Error handling
10.5 Diagnostics
10.6 Integrity and Recovery
10.7 Testability
10.8 Portability
10.9 Localization
10.10 Usability
10.11 Summary

<--Prev page | Next page -->

10.5 Diagnostics

If an error is detected, what next? Whether you decide to limp on or shut down immediately, it is good style to give as much information as possible to help the user understand the problem and the programmer fix it.

Diagnostic code may be used before and after product release. Pre-release code will be liberally spread throughout the code, and will help in the early debugging and tuning activities. It should be possible to turn on an off sections, so that a problematic subsystem may be investigated without additional diagnostics being given. Post-release code should have much of this code conditionally-compiled out, especially if it affects program performance.

10.5.1  Error messages

Error messages need to be targeted toward the type of user reading them: it is no good telling a secretary using a wordprocessor that the system call 0x03FF has returned an error number 5, or even that the spool file header is corrupt. It is often useful to offer advice, even if it is simply to call someone who can understand the problem. It may also be useful to have a hierarchic error message system, with lower level messages giving more technical detail. A unique number added to each error message can be useful for when the message is to be reported back to the maintainer (especially if the program text has been translated into another language, such as French):

A file has been damaged, please tell your office systems coordinator (132).
..
Spool file header corrupted, restart system to clear (544).
..
System error: call = 0x03FF, error = 5

----------------------------------------------------------------------------

If the system is not interactive, this type of message cannot be given immediately. It is still useful for later analysis and may be added to a log file.

10.5.2  Log files

Log files are useful places to silently put information which the program user needs not see immediately, but which provides useful information at a later date. Typically this will record data about minor problems which were recovered, and may also include data about the way the user is using the program.

A typical log entry will be uniquely identified by date and time. An error description will also uniquely identify the error and its location.

Log files should, of course, be maintained. A user will not be happy to find all of his disc space being taken up by an apparently useless log file! Thus, for example, only one day's data may be kept.

10.5.3  Trace information

It will help the maintainer fix the problem if a history of what happened before the error occurred is kept. This can either be from special code or from stack dumps. This may include functions called, parameters passed, data changed. Typically, the last 'n' actions may be kept in a circular buffer or file.

10.5.4  Dumps

Virtually any other information may help fixing of the problem. This will include dumping of variables, keyboard buffers (useful to find what the user just pressed!). It is also very useful if the data is dumped in human-readable format, or if an interpretation program is available (dump-cracking is for gurus who have plenty of time!).

<--Prev page | Next page -->