Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!usc!zaphod.mps.ohio-state.edu!unix.cis.pitt.edu!pitt!willett!ForthNet
From: ForthNet@willett.pgh.pa.us (ForthNet articles from GEnie)
Newsgroups: comp.lang.forth
Subject: Documenting
Message-ID: <2797.UUL1.3#5129@willett.pgh.pa.us>
Date: 21 May 91 01:59:55 GMT
Organization: (n.) to be organized.  But that's not important right now.
Lines: 28


 Date: 05-12-91 (12:42)              Number: 2197 of 2202 (Echo)
   To: DENNIS RUFFER                 Refer#: 2135
 From: RAY DUNCAN                      Read: NO
 Subj: FORMATTING FORTH SOURCE C     Status: PUBLIC MESSAGE
 Conf: FORTH (58)                 Read Type: GENERAL (+)

 At LMI, we experimented with shadow screens, but gave up on them almost
 immediately.  They are too limiting as documentation, and they also
 exacerbate the classic problem of separating documentation from code and
 helping them get out of synch.  We have grown to prefer the "vertical"
 coding style.  While it's true that you often don't get more than one
 definition on a screen this way, maybe 2 or 3 if they are really short,
 the documentation is right there and is easy to keep up to date.  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.

 NET/Mail : LMI Forth Board, Los Angeles, CA (213) 306-3530
 <<<>>>
-----
This message came from GEnie via willett.  You *cannot* reply to the author
using e-mail.  Please post a follow-up article, or use any instructions
the author may have included (USMail addresses, telephone #, etc.).
Report problems to: dwp@willett.pgh.pa.us _or_ uunet!willett!dwp