by Richard Russell, March 2010
Note: This article specifically applies to re-usable code libraries. Another use of the INSTALL statement is as a means of splitting a large program into modules. Several of the guidelines listed below do not apply to that use, apart from the prohibition on the use of line numbers and labels, and the necessity to enable the Crunch embedded program files compile option.
A BBC BASIC for Windows LIBRARY is a special kind of program file which contains functions and/or procedures which can be called from the main program in which it is INSTALLed (or from another library installed by that same program). Fundamentally it is no different from any other program file except that it contains no 'main program' (unless you wish to include some code which will report an error if it is executed directly, see Preventing a library from being run). In addition, a library must be saved as an internal format (tokenised) .BBC file rather than a plain-text (ASCII) .BAS file. If you attempt to INSTALL a library saved in the wrong format a Bad library error will result.
Having stated that a library is fundamentally no different from an ordinary BBC BASIC program, special considerations apply which don't (at least to the same extent) to a conventional program. Some of these are technical restrictions (for example that line numbers cannot be used) and others are issues of style which become much more important in the case of a re-usable library. When you write a program for your sole use you can decide whether you want to risk the potential consequences of ignoring 'good practice', but when writing a library (assuming that you intend to publish it for others to use) you mustn't impose such risks on your end users. For them to use your library with confidence, it should adhere to the programming guidelines listed below.
An overriding consideration, which lies behind many of the recommendations, is that a library must be as self-contained as possible. Ideally it should not be dependent on any specific characteristics of the program in which it is INSTALLed, nor should it impose any avoidable restrictions on that program.
DEF PROCtest PRIVATE list,of,privates ON ERROR LOCAL RESTORE LOCAL : ERROR ERR,REPORT$ REM Rest of procedure here ENDPROC
Several of these recommendations are also valid for ordinary functions and procedures within a conventional program, but do not have the same importance when they affect only that one program. Only in the case of a published library, when the reliability of an end user's program could be affected, should they ideally be strictly followed.