Scientific Forth Library Coding Guidelines



1.  The source code should be declared public in some manner.
    This can include: public domain, Gnu style copyleft, or copy-
    right with permission to use. Use whatever form your
    conscience or employer dictates.

2.  The code should document the description of the algorithm so that
    a user who needed to could look up the source of the algorithm.

3.  The code should contain a version number and date within the
    comments section.

4.  The code is to be in ANS Forth and assume the operators given
    in the FLOATING POINT extension wordset of the dp-ANS-6 proposal.
    In addition, additions and extensions and other modifications of 
    the ANS-94 Standard which have been approved by the Forth 200x 
    project (see http://www.forth200x.org/forth200x.html) may be used, 
    provided that their use is pointed out in the documentation.

5.  Assume a separate floating point stack. That is, no fp
    numbers go on the data stack.

6.  Acceptable library routines are not allowed to modify the system;
    that is, after loading your files the system should still
    compile ANS-compliant FORTH code.

7.  Any environmental dependencies must be stated in the header. 
    For example
        \ Employs the file array.seq to implement }, }}, etc.
        \ Assumes segmented (PC-style) addressing with long-
        \ form addresses.

    If the code requires other files, it is best not to have the code itself 
    attempt to load those files usings words like NEEDS , REQUIRES , etc.  
    Those words vary too much from system to system.  Even the ANS-compliant
    S" somefile.fth" INCLUDED  should be avoided, since the file may be already
    present.  It is quite acceptable to include a commented-out line of that 
    sort in the headers as a way of documenting the need for the file.

    Similarly, if the code uses non-ANS words which may well be provided by the
    system, it can be useful to provide commented-out ANS definitions, as in
        \ The code uses these non-ANS words
        \    : F+! ( addr -- ) ( F: r -- )  DUP F@ F+ F! ;
        \    : FSQR ( F: r1 -- r2 ) FDUP F* ;

8.  All submissions should include a test driver and some means of
    verifying that a local compilation ran properly.

9.  Use the array and matrix notational convention from

      Noble, "Scientific FORTH: a modern language for scientific
      computing" (Mechum Banks Publishing, Ivy, VA 1992)
      ISBN 0-9632775-0-2, p. 105ff.

    Implementations for various systems are provided in some of the auxiliary
    files provided with the Library.  Here is a description of the notation:

      array names end with {, {{, {{{ etc. depending on whether they are
        1-, 2- or 3-dimensional.
      }, }}, etc. are FORTH words.
      The resulting notation looks like:
                A{ I }          ( adr of I'th element of A{ )
                M{{ I J }}      ( adr of I,J'th element of M{{ )
                etc.

    Arrays are ZERO based.

10. The convention for passing function or subroutine names is likewise
    that suggested in Noble's book (p. 162 ff). Basically, suppose one
    wants to integrate a function g(x) = sin( 1 / x ) from 0.01
    to 10^4. Then one might say ( f: signifies the fp stack)

    : g(x)  ( f: x -- sin[1/x] )  1/F  FSIN  ;
    USE( g(x)  % 0.01  % 1.E4  % 1.E-5 )INTEGRAL

    Used interactively, USE( leaves the execution token of the
    following word on the data stack. It is then available for
    the subsequent words to employ.

    Again, there are auxiliary files which provide implementations
    for various systems.

11. If floating-point local variables are used, the syntax should be
    that provided by the various auxiliary files, even though nicer
    alternatives are available in some systems.  :-)

    Similarly, the syntax provided for other capabilities, such as
    means for hiding words in PRIVATE wordlists, should follow that provided
    in the auxiliary files.

12. The naming conventions and syntax for COMPLEX operators and functions 
    should generally follow those of the file complex.fs (Algorithm #60), 
    even if that file is not actually used.  In particular, names for complex
    entities should generally start with z, as in 
                   zdup, z@, z*, zexp, z., etc.,
    and complex floating point values on the floating point stack 
    should have the imaginary part uppermost, that is that 
            z=x+iy  has the stack diagram  ( f:  x y ).


The aim of these guidelines and conventions is to provide code that

I)  can be read and understood by programmers familiar with scientific
    coding in other widely used languages such as Fortran and C.

II) can be loaded and run with a minimum of effort on any ANS Forth 
    system, so that a potential user can explore whether the capabilities
    provided are useful for his problem.  It is to be expected that
    someone making extensive use of a Library routine will modify it
    to take advantage of any special features of his own system and to
    interface it efficiently with the rest of his programs.


Browsing through some of the existing Library routines by different authors
will provide examples and suggestions for how these aims can be pursued.
Always remember: short definitions, well chosen names and thorough 
documentation help enormously.


                                       [latest revision 05 January 2011  cgm]