Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!usc!cs.utexas.edu!uwm.edu!linac!att!pacbell.com!ucsd!sdcc6!ir230
From: ir230@sdcc6.ucsd.edu (john wavrik)
Newsgroups: comp.lang.forth
Subject: Re: Modular coding style
Message-ID: <19607@sdcc6.ucsd.edu>
Date: 21 May 91 05:39:04 GMT
Organization: University of California, San Diego
Lines: 73


> Ray Duncan writes:
> In our larger programs, we make heavy use of the module concept, using a
> lot of little files which each contain a functional subset of the source
> code, and a "master" application file which holds the definitions of global
> variables and a bunch of "include" statements for the other files.  This
> approach seems to work well for us and also places pressure on us to
> keep the interfaces between the modules small and clean.

In mathematics, many of the important data types are compound -- built 
from specific simpler types. In "pop bead" fashion, we assemble new 
systems by joining modules together. An interesting feature of Forth 
is that the dictionary structure makes it possible to extend features 
and operations to compound structures via redefinition -- a much 
simpler and more efficient approach than the use of property lists, 
etc. found in LISP-based systems. [Traditional Forth is actually a 
much better language for mathematics than most languages.] 

Modules tend to be fixed structures (once they are stabilized) that 
define abstract data types and fundamental operations upon them. We 
use (as in F83) DOS files of Forth blocks for the modules -- so that 
they can be easily added to different applications.

The problem of where to put comments is a fascinating one. We've tried 
several alteratives (both in research work and in teaching). Including 
a great amount of comments in the source code has proven to have a 
self-defeating effect: the comments hide the code and actually make it 
harder to read. For research we have found that, in addition to the 
modules, individual words often become important in future work -- so 
a separate glossary (in the form of a database) is used to describe 
words and indicate their location in source code files. For 
instruction, students are encouraged to describe the intended function 
of words in a separate place in the source code (e.g. above the 
definition itself) and restrict commenting within a definition to 
stack diagrams or brief comments which help a reader understand the 
code. [Neither of these practices are firm -- but they seem to be the 
best so far.] 

Two different problems are being dealt with here: 

(1)  In research:  how to make code as widely useful as possible;
     and how to locate words written in the past which solve current
     problems.

     Here the answer seems to be a modular approach to coding -- with
     as much use of data abstraction as possible. Coupled with the
     use of separate files for major modules and a data retrieval
     system for locating important words.

(2)  In teaching:  how to make the communication of code (particularly
     from student to teacher) comprehensible in the face of a variety
     of writing styles and levels of competence.

     Here the answer seems to be to have the programmer's intent
     recorded -- but not in a way that blocks reading of the code.

Forth has an undeserved reputation as a "read only" language -- which 
probably comes from the absence of any accepted conventions for 
writing. One of the strong points of Forth is that it does support a 
modular style which, if word names are carefully chosen, enhances 
readibility (to say nothing of utility) of code. Once a module has 
become firm, however, there may be good reason to separate comments 
(with rationale, description of how the code is written -- 
limitations, etc) from the code itself -- leaving code that is clearer 
on the one hand, and documentation that can be accessed in a flexible 
and useful way on the other. 

                                             John J Wavrik 
        jjwavrik@ucsd.edu                    Dept of Math  C-012 
                                             Univ of Calif - San Diego 
                                             La Jolla, CA  92093