Documenting Forth 
Author Message
 Documenting Forth

        MC: Mike Coughlin       JN: Julian Noble
        RB: Roger Bicknell

MC:    I don't know if I am usually more coherent, but I am usually
MC: more agreeable. For many years I've asked people who would greatly
MC: benefit from using Forth why they didn't do so. The answer I
MC: received the most offen (from people who knew what Forth was) is
MC: "Forth is unreadable" or "Forth is a write only language". I'm sure
MC: that we have all had that experience. But do we pay any attention?
MC: NO! That is why I get so e{*filter*}d about this subject.

Perhaps one reason why many people don't get e{*filter*}d is that they
have managed to learn Forth on their own, and don't really have
anything much to say?  What do the people who TEACH Forth have to
say about this?  I am esp. thinking about the commercial vendors
who offer classes.

JN: I did not say one actually *** could *** get by without comments, I
JN: was merely stating the *** ideal ***, as I understand it.

MC:     In my opinion, you've turned the situation upside down. The
MC: ideal is to explain the program in clear technical English (or
MC: German, French, etc.).  It is just as useless to write a program
MC: without comments as it is to try to publish a scientific paper that
MC: contained only mathematical formulas.

I find myself agreeing with both of you here.  The code should be clear
enough to understand what it is doing.  But, comments are needed to
explain _why_ the code is doing what it is doing, and perhaps what (some
of?) its assumptions about the rest of the environment are.

MC: If the commenting is only done on a single level, you have to
MC: be a detective to reconstruct the missing details.

Agreed.  At the lowest level, where the comments "echo" the code, they
add nothing.  To the degree that comments rise about that level, they
are correspondingly more valuable.

MC:     Since I know both Forth and fortran, I am not able to judge if
MC: mixing them together is an improvement. Is the use of the algebraic
MC: expressions of Fortran, Basic, Pascal and C really a help here?

To someone not familiar with any comuter languages, Fortran is likely
to resemble the familiar algebraic infix notation.

MC:     Since we are all interested in promoting Forth, why don't we
MC: try to do research in finding ways of making Forth the easiest
MC: computer language to read? Lets look for the fastest way to
MC: understand a Forth program with the same dedication we look for
MC: ways to make the fastest executing program. We don't have to change
MC: the Forth language, just the way it is documented.

I think that is a lauable goal.  Given the ideosyncratic nature of Forth
programmers (so the stereotype says anyway), I haven't the foggiest idea
how to do that.

RB: Forth lends itself to be mutated into the "perfect" language in
RB: which to express the solution.  Thus the code which does the
RB: mutating should deal with the nature of the problem and the
RB: documentation should reflect this and also answer the WHY question:
RB: "Why is this the perfect vernacular in which to express the
RB: solution?"

Agreed, except the "perfect" part.  The questions are "Why was this
method chosen for expressing the solution?  What tradeoffs were
considered?  What were the justifications/reasonings behind these
particular choices?"


Fri, 01 Dec 1995 19:27:02 GMT  
 Documenting Forth

In an earlier discussion on this thread (with Mike Coughlin) I expressed the
opinion that "ideal" Forth code should be as close to self-documenting as
we can achieve through the following techniques:

        1. Expressive or telegraphic choice of names

        2. Proper factoring/short definitions

        3. Expressive notations for complex situations.

In Category 3 I mentioned my improved matrix notation (that eliminates
the ambiguity of "natural" Forth style) and the FORmula TRANslator that
I have found effective in keeping the equation format (that scientists
and engineers are used to) in the source code, while compiling to Forth
(that would indeed be unreadable for equations with many factors or terms).
I have also --as some readers of this news group may be aware-- devised
a better notation for finite state machines, in which a state-transition
table description (that I had previously included as a comment) actually
gets compiled. In other words, I used the flexibility of the Forth compiler
to write a state-machine compiler. A compiled state table is ipso-facto

But let me add here my agreement that self-documenting code, while a fine
thing in itself, and a worthy goal of our endeavors, is not sufficient
for complex projects. Documenting for such cases, adequate to permit
a new graduate student, say, to pick up the program listings for some
aspect of his advisor's group's work (data acquisition and reduction,
interfacing, control, etc. etc.) two years after it was written, and in
a short time be able to understand and modify it; requires a complete
description of the problem, sections on details of all parts of the system,
discussion of the alternatives and choices and the philosophy of the
approach, and so on.

One of my goals in my Forthcoming presentation at the 1993 Rochester
Conference will be to exhibit code that achieves these lofty aims. ;-)


Fri, 01 Dec 1995 23:09:01 GMT  
 Documenting Forth

> What do the people who TEACH Forth have to
> say about this?  I am esp. thinking about the commercial vendors
> who offer classes.

I am not sure who you mean here, possibly FORTH, Inc. or MPE, Ltd.

However, I would like to remind you and everyone who reads this
news group that a recent survey (posted on of some 300
universities around the world revealed that *** not a single one ***
teaches Forth as a first computer language. And yet, I am sure that
the Forth community, most of whom use several languages as a matter of
course, could think of plenty of reasons why Forth could be an
*** ideal *** first programming language.


Fri, 01 Dec 1995 23:17:30 GMT  
 Documenting Forth

+I am not sure who you mean here, possibly FORTH, Inc. or MPE, Ltd.

I wasn't referring to any particular vendor.  I was interested in getting
feedback from any "Teachers of Forth" (esp. Vendors who get directly paid
by the students).


Sat, 02 Dec 1995 21:52:46 GMT  
 Documenting Forth


> Perhaps one reason why many people don't get e{*filter*}d is that they
> have managed to learn Forth on their own, and don't really have
> anything much to say?  What do the people who TEACH Forth have to
> say about this?  I am esp. thinking about the commercial vendors
> who offer classes.

Our courses are more aimed at the "engineer" rather than the
"computer science theorist" who have a job to do and haven't got time
to sit down and tinker for a couple of weeks.

However we have recently changed the slant that we are putting on the
(beginners) courses. We make no attempt to TEACH the language. That would
be a waste of time, since the vocabulary of any language is only
learnt in the use of it. What we DO attempt to do is give the course
delegates a grounding in the language, and the philosophies behind

This means that good (ie. well factored, well commented, reusable)
code is produced from the outset, and hence the "write only" image
simply is not a factor.

It also means that the delegates understand their own code better,
which means that confidence in using the language is gained. (For C
programmers: when you first learnt C how confident were you about
function pointers, How often did you use them) Being confident about
a language is the first step in using it to its full potential.

Alternatively, we could sit down and throw hundreds of words at
someone, have them take in none of them, and simply duplicate what
is already in the glossary.

I know which I would rather teach. I think I know which I would
rather have taught to me.

Gary Ellis

MPE, 133 Hill Lane  | tel  +44 703 631441          | Developers and  Vendors
Southampton SO1 5AF | fax  +44 703 339691          | of Forth  Compilers and

Sun, 03 Dec 1995 02:55:58 GMT  
 [ 5 post ] 

 Relevant Pages 

1. Cession gratuite documents FORTH

2. Well documented fig-Forth on Simtel

3. Latest ANSI-Forth document?

4. Evolution of Forth (was: Documenting)

5. FORTH internals document

6. Global Document Handling Template - Document Send Extension

7. document, document

8. Getting Forth related files (was: Forth primer/teaching Forth)

9. Forth in Forth vs. Forth in assembly language

10. Forth in Forth vs Forth in assembly

11. Forth in Forth vs. Forth in assembly language

12. ans forth link broken at


Powered by phpBB® Forum Software