From: nick@sw.stratus.com (Nicolas Tamburri)
Newsgroups: comp.lang.forth
Subject: Re: Documenting
Date: 31 Dec 1992 15:54:41 GMT
Organization: Stratus Computer, Inc.
Distribution: world
NNTP-Posting-Host: osa.sw.stratus.com

In article <1992Dec31.112348.12448@sol.ctr.columbia.edu>, penev@venezia (Penio Penev) writes:
> Mike Haas (mikeh@starnine.com) wrote:
> : > From: MARK VANDITTA
> : >
> : > Is it my imagination, or do most Forth programmers lack formal
> : > instruction in structured coding?

Unless you are using 'structured coding' in a matter with which I am not familiar,
it is your imagination.  Forth is a very structured language where you have to go
out of your way to be unstructured.  Most Forth programs I've read keep this
philosophy.  The rest of the message leads me to believe that you mean coding
style:

> : > 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

I've always understood the comma as being a convention for those words which
compile data into the dictionary and bump HERE, (if HERE still applies...)  In which
case, the comma is not needed (as with all syntactic fluff,) but useful.

But you miss the point:  My first assembler allowed me to put multiple instructions
on a single line.  If I had done that in product source,  my hands would have been
cut off at the wrists :-)    This is not just a matter of putting multiple spaces
between code phrases to enhance readability. The rest of the line is meant for
COMMENTS.  This is especially true (and practically universal) for assembler code.
The only argument to the contrary was put forth (NPI) by Brodie in "Thinking Forth"
namely that lots of comments don't necessarily mean a good commenting style if
they are of the "Put 1 in the AC..." variety. I agree, but I'm talking about
useful comments in this discussion.

Mike is absolutely correct:  Screen vs. File wars not withstanding, this coding
style IS a direct result of growing up with screens.  By the time you have indentation,
the instruction, and tabbing to the comment column, you may get 32 chars of comments,
unless you want to continue to the next line making things even uglier.  Why bother?
In older systems where a screen was always 1K of storage, no matter how much text
was in it, you didn't generally like to waste disk storing 1 definition per screen
so you could do pretty indentation of each instruction.

It's about time we moved away from it, especially where CODE words are concerned.
I wouldn't mind seeing this happen to some higher level definitions as well.

> [Sample code sections deleted.]

They were very clear to me,  but the original writer appeared to be a novice
trying to learn the language.  Perhaps he can tell us how clear they were to him.

> 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.

Not to defend C for readability, but I consider the procedure name and
variable declarations useful, if not vital, information when looking at a program.
In any case, you can feel right at home with C by reformatting the above program to:

procname(args){  variables declaration;  body  }

(Note multiple spaces between significant program sections.)

For short routines, this should be perfectly acceptable.  Don't bother with the
empty lines between definitions, if you want to stick to the convention in your
sample screens.

[Lots of other screen justification and sample code deleted.]

I'm not denying screens are useful, and I definitely do not want to start yet
another war.  But to deny what Mike said about the evolution of the coding style
as it relates to screens is to deny the obvious, and that is really what this
discussion is about.

								/nt