From: penev@venezia (Penio Penev)
Subject: Re: Documenting
Organization: Rockefeller University
Date: Thu, 31 Dec 1992 11:23:48 GMT
X-Newsreader: TIN [version 1.1 PL6]
Reply-To: penev@venezia.rockefeller.edu
X-Posted-From: venezia.rockefeller.edu
NNTP-Posting-Host: sol.ctr.columbia.edu

Mike Haas (mikeh@starnine.com) wrote:
: In article <4195.UUL1.3#5129@willett.pgh.pa.us> ForthNet@willett.pgh.pa.us (ForthNet articles from GEnie) writes:
: >Category 3,  Topic 3
: >Message 8         Mon Dec 28, 1992
: >ELLIOTT.C                    at 12:26 EST
: > 
: > ----via CRS Premium Bulletin Board -
: >  USR Dual Standard 16.8K  (416) 629-7000
: >
: > Date: 12-19-92 (13:38)
: >   To: ALL
: > From: MARK VANDITTA
: > Subj: FORTH CODING STYLE
: >
: > Is it my imagination, or do most Forth programmers lack formal
: > instruction in structured coding?  I have found that most Forth
: > programmers write code that is even more unlegible than that of C
: > programmers raised on DEC Writers.  Why do Forth programmers
: > insist on packing so many words on a single line at the sacrifice
: > of clarity?
: 
: > Here's an example from
: > Frank Sargent's Pygmy:
: >
: > CODE 0branch HERE T0BR !
: >  AX LODS, DI BX CMP, 0=, IF, AX SI MOV, THEN, BX POP,
: >  NXT,   END-CODE
: >
: > Now I really like what Frank has done with Pygmy, but his coding
: > style leaves a lot to be desired.  I had to reformat his code to
: > be able to follow its structure.
: >
: > CODE 0branch
: >     HERE T0BR !
: >     AX LODS,
: >     DI BX CMP,
: >     0=, IF,
: >         AX SI MOV,
: >     THEN,
: >     BX POP,
: >     NXT,
: > END-CODE
: >
: > Granted, I used 10 lines instead of 3, but it is now clear to me

The same could de _indented_ this way:

CODE 0branch    HERE T0BR !
    AX LODS,   DI BX CMP,   0=, IF,  AX SI MOV,  THEN, 
    BX POP,   NXT,   END-CODE

There is really no need to have the commas  after the ASSEMBLER words
and NXT can be a macro, which does the END-CODE. With the definitions

BX CONSTANT TS ( Or TOS if You prefer it) 
SI CONSTANT R

in the beginning, the word may look like 

CODE 0branch    HERE T0BR !   LODS   
    DI TS CMP   0= IF  AX R MOV  THEN 
    TS POP   NEXT

And still be on three lines. Of course I would write this as 

CODE 0branch    HERE T0BR !   LODS   DI TS CMP
    0= IF  AX R MOV  THEN   TS POP   NEXT


Conside the following code:

 1 : RP+   4 R R addi ;
 2 : RP-   -4 R R addi ;
..
 9 : SP+  4 S S addi ;     
10 : SP-  -4 S S addi ;

 0  ( Structures)                                      PSP 11/12/92
 1 : ?CELL ( n - n ?)  0 ;
 2 : ?RANGE ( n - n)   ?CELL ABORT" Out of range" ;
 3 : OFFS ( s d)  OVER - ?RANGE  2/ 2/  SWAP 2- TW! ;
 4 
 5 : begin   HERE  -CODE ;
 6 : if  ( n - a)  INST!  W, 0 W,  begin ;
 7 : then ( a)  begin OFFS ;
 8 : else   0 Z# if nop  SWAP then  -4 GAP ;
 9 : until ( a)  if  SWAP OFFS ;
10 
11 : Drop1  S ) 1 lw  SP+ ;
12 : Drop1+   S ) 1 lw  SP++ ;
13 : 0check ( - a)  Drop1  TS Z# if  1 TS mov  -CODE ;
14 
15  

 0 \   Compiler directives                             PSP 11/12/92
 1 : BEGIN ( - a)   begin ;   TARGET
 2 : UNTIL ( a)  0check  SWAP OFFS ;   TARGET
 3 : AGAIN ( a)  j nop ;  TARGET
 4 : THEN ( a)  then ;  TARGET
 5 : IF ( - a)  0check ;   TARGET
 6 : WHILE ( a - a a)   [COMPILE] IF  SWAP ;   TARGET
 7 : REPEAT ( a a)   [COMPILE] AGAIN  [COMPILE] THEN ;   TARGET
 8 : ELSE ( a - a)  else nop ;   TARGET
 9 
10 : FOR ( - a)  TS TR mov  RP-  Drop  TR dec
11     begin  4 R TR sw ; TARGET
12 : NEXT ( a)  nop TR Z= until  TR dec  RPOP ;  TARGET
13 : IFOR ( - a a)  TS T1 mov  0check  -1 T1 TR addi  RP-
14     begin  4 R TR sw ;  TARGET
15 : NEXTHEN ( a a)  [COMPILE] NEXT  [COMPILE] THEN ; TARGET 

This is code for R3000, which has branch delay slots, load delay slots
and three register instructions. INST! and -CODE are for the optimiser.

Do You need vertical format?	No
Do You need indentation?	No
Do You need three lines?	Extremely unlikely
Do You need two lines?		Rarely
Do You need shadows?		Only here and there

: 
: This is a side-effect of those ever-so-limiting 64 x 16 damn SCREENS!
: 
: In normal file-based environments (which all other languages are
: standardized on), you don't have to worry about packing as much
: into that tiny space as possible.

You don't have to wory about about packing as much info in the screen
either. One screen can hold 5 to 12 words (subroutines). This is
enormous amount of info. The equivalent amount in C is more, that You
can fit even on today workstations' 17" screens. Consider the overhead
in C:

procname(args) {
	variables declaration;
	body
}  
empty line

You have four lines per entry, which cary basically no information.

: 
: In otherwords, with SCREENS, there is no way to create pretty,
: indented, clear code.  You either have to spread it over

Look at _any_ 10 screens of FORTH, Inc.'s code and You can find 9 to
be pretty, clear, UNindented code. 

: several screens (requiring constant flipping in an editor), or
: pack the hell out of each line (to get it all visible in one place).
.. or factor the words better.

: 
: SCREENS only display 16 lines at a time.  More dark ages stuff which
: continues to cripple Forth's image.
: 
: Personally, I'll probably never work with SCREENS again, as I don't
: anticipate any more SBC projects.  That's fine with me, as Forth

I have worked on i486/MSDOS and R3000/UNIX and find it much more
convinient to work with screens.

: really does interface well with modern OS's (even some that aren't
: so modern), and I'm spoiled by working with standard text files
: for about 7 years now.  I can't imagine ever preferring SCREENS...

There are things, that files are very unsuitable for. consider a
sextet index of a Monte Carlo Simulation Program:


       420 \ Polymers - Main                                   PSP 22/11/92
       421 \   Polymers - local                                PSP  3/06/92
       422 \   Polymers - contd.                               PSP 30/05/92
       423 \ Energy discretization                             PSP  2/11/92
       424 \ Parameters of the polymer simulation              PSP 28/05/92
       425 \ Initial values of the parameters                  PSP  2/06/92
       426 \ Interaction - structures                          PSP  9/05/92
       427 \   Horizontal interaction                          PSP 28/05/92
       428 \   Vertical interaction                            PSP 28/05/92
       429 \   Location interactions                           PSP 15/04/92
       430 \   2D-Array calcualtions                           PSP 21/05/92
       431 \ T-dependent energies for the run                  PSP 29/05/92
       432 \ Polymer latice                                    PSP 17/04/92
       433 \   Neibours with cyclic boundary conditions        PSP 27/04/92
       434 \ Calculate energy index                            PSP 29/05/92
       435 \ Update sites                                      PSP 29/05/92
       436 \ Dynamics                                          PSP  5/06/92
       437 
       438 \ Tabulate all energy differences                   PSP 29/05/92
       439 \   Access energies and probabilities               PSP 29/05/92
       440 \   Build energy and probability                    PSP 29/05/92
       441 \   Horizontal connectivity                         PSP 26/04/92
       442 \   Vertical connectivity                           PSP 26/04/92
       443 \ 
       444 \ Cluster statistics - structures                   PSP 27/04/92
       445 \   Walk clusters                                   PSP 27/04/92
       446 \   Collect cluster lengths                         PSP 22/05/92
       447 \   Write cluster statistics to disk                PSP 22/05/92
       448 \ Concentration of monomers                         PSP 25/04/92
       449 
       450 \ Stat variables                                    PSP 21/05/92
       451 \   Definition of stat variables                    PSP 21/05/92
       452 \   Statistics                                      PSP 21/05/92
       453 \   Compute thermo-dynamic properties from stat     PSP 20/05/92
       454 
       455 
       456 \ Swapper                                           PSP 17/05/92
       457 \ Swapping interface                                PSP 17/05/92
       458 \ Change Lattice side and reboot                    PSP 14/05/92
       459 \ 96-bit data                                       PSP 22/05/92
       460 \ Statistical words                                 PSP 30/05/92
       461 \   Statistical words                               PSP 31/05/92
       462 \ Data base management                              PSP 20/05/92
       463 \ Additional operators                              PSP 21/05/92
       464 \ Invalid fields                                    PSP 24/05/92
       465 \ File of samples                                   PSP 21/05/92
       466 \ Thermodynamic quantilies                          PSP  3/11/92
       467 \ File of lengths                                   PSP 22/05/92
       468 \ File Density of states                            PSP  8/11/92
       469 \ Produce SAMPLES from TDQ                          PSP 20/05/92
       470 \ Convert SAMPLES Old > New                         PSP  3/06/92
       471 \ Locate L in the file                              PSP 21/05/92
       472 \ Produce Thermo Dynamic quantities from samples    PSP 24/05/92
       473 \ Avaraged statistics                               PSP  6/06/92
       474 \ Cumulant computation from samples                 PSP  6/06/92
       475 
       476 
       477 HEX \ Optimizing                                    PSP 23/04/92
       478 \ Internal registers                                PSP  5/05/92
       479 

Try to have this with files. And talk about documentation afterwards.

: and I don't care how cool a Forth SCREEN editor you have... there are
: much better ones for text files.
: 

This is not quite true. I've tried almost all of the editors on the PC
(pe2, e3, kedit, edit, professional editor (IBM), WINWORD) and emacs on UNIX.
None is better for editing programs that the screen editor I use. The
reason is very simple. Even though the good editors have their
languages, not is a flexible as FORTH is. They are pretty narrow too.
On the contary one has the entire source of his editor in FORTH and
implements whatever functions he considers usefull. And one ends up
with a highly tuned to himself editor. 


: I hope I never again have to wind my way trough something like...
: 
: 5 LOAD 8 LOAD 23 LOAD 100 110 THRU 56 LOAD 13 LOAD etc. etc. etc
: 

You can write extremely cryptic code in FORTH, as well as in almost
any languge. An usual load screen, though looks like:

 0 ( Electives)   DECIMAL
 1 : <CREATE>   >IN 2@   SWAP 1024 * + ,  (CREATE) ;
 2    ' <CREATE> 'CREATE !     4 CONSTANT B/H  ( 0 if no  LOCATE)
 3 ( Aids) 12 LOAD  13 LOAD  14 LOAD 11 HELPS  10 LOAD  23 LOAD
 4 ( Disk retries   33 LOAD     6 LOAD)  2 LOAD
 5 ( 32-bit)  15 18 THRU   ( 21 23 THRU)  ( char)  19 LOAD
 6 ( L.C. Editor) 20 LOAD  ( UNIX Date & Time) 34 35 THRU
 7 ( Calendar)  31 LOAD   TODAY @ .DATE  ( Loops)  4 5 THRU
 8 ( Time)  32 LOAD   .(  Time )  @TIME .TIME
 9 : SYSTEM   11 DATED  ."  Time "  @TIME .TIME ;
10 : ONDISK   7 OFFSET @ -  HELPS ;     7 LOAD
11 ( Tasks)  24 25 THRU   \ Printer)  28 LOAD  ( Runner)  29 LOAD
12 ( Screen editor)  1 LOAD \TERM    222 LOAD
13 : HELP   SYSTEM ;    GILD
14 ( Terminal: ANSI)     ' ?CREATE 'CREATE !
15 \S   polyFORTH II Level 4      31 Jan 1992 


FORTH is a extremely democratic language. You can write _whatever_ You
want (and be responsible for this afterwards). I won't argue, that
screens is better or worse than files for everybody. I'll argue, that
it's beter for me.  And this is the beauty of FORTH - You can express
Your abstractions in code. FORTH is neither high level, nor low level.
It is of one particular level - _Your_ level.

-- Penio.