Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!crdgw1!uakari.primate.wisc.edu!sdd.hp.com!mips!pacbell.com!att!linac!pacific.mps.ohio-state.edu!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: Formatting Forth source code
Message-ID: <2753.UUL1.3#5129@willett.pgh.pa.us>
Date: 13 May 91 11:56:51 GMT
Organization: (n.) to be organized.  But that's not important right now.
Lines: 65

Category 2,  Topic 13
Message 20        Fri May 10, 1991
D.RUFFER [Dennis]            at 01:31 EDT
 
Bob, just a couple of comments on your formatting style (:since you opened
yourself up to it:)

Lower case:

I've seen many people adopt this before, and I can understand how someone who
has a background in other languages (that aren't case sensitive) might prefer
it.  However, in my opinion, those people and languages are throwing away half
the alphabet.  I prefer to work with Forth's that _are_ case sensitive, and I
tend to use lower case for low level words.  That way, I have a built in
indication of user interface words, with easy to remember sublayers.

Comment/phrase:

I used to work (some 12 years ago) on RPG programs written by IBM programmers.
They tend to comment everything and in some cases it got to the point that
could not even find the "real" source code lines.  Personally, I can read the
code much better than I can read the comments, that is why I work in a given
language.  At the most, all I care about is a brief description of _why_ a
given module is needed.  I _do not_ need a comment that tells me that the
phrase: >IN OFF  resets the input stream.  Something like that just "gets in
the way" when I'm trying to figure a section of code out.

My personal opinion is that you should be able to _read_ Forth source code. 
The names should be choosen carefully so that the resulting modules "say" what
they do.  Some of this comes from internal naming conventions (i.e. "/" means
initialize, ">" means pointer to..., etc.), but most comes from imaginitive
vocabularies (i.e. a thesaurus).

Vertical coding:

Maybe this comes from my long time work with BLOCK files, but putting only a
few things on a line seems to be wasteful to me.  For me, 2 spaces is enough
to seperate phases within Forth.  I want to get as much of a given concept as
I can on 1 page.  As far as lining up structures goes, I sometimes find that
useful, but again, I will only use it if the vertical space is not overused.

Stack diagrams:

Absolutely essential at the beginning of the word, but I agree with you about
line by line analysis.  If it is that hard to understand what is happening on
the stack, then the word should be refactored.

Comments in general:

Not to belabor the point, but I feel that it is important.  A comment that
tells me _what_ something does is not near as useful as a comment that tells
me _why_ it does it.  What can be determined by examining the code, but why is
often buried within the designer's mind.  As a manager, a programmer's time if
very valuable.  I do not want him/her spending that time duplicating efforts
by restating what the code does.  Rather, I value the time invested in
recording the reasons why the program is organized that way it is.  It is much
harder to write (as a programmer) but much more valuable years later when the
original programmer may not even be available for consultation.

Just some thoughts.   :)   DaR
-----
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