Re: Documenting Forth code was [ Re: Technics to imp rove (?) the sources readability.]

The purpose of the code as I read it is to postpone the execution of a word
to later in the source code to make the definition more readable. I don't
see much wrong with this: after all, the beauty of Forth is that you have
this kind of flexibility. I appreciate the effort and found the code
interesting. However, I am still on the "somewhat skeptical" side of the
fence.

For what it is worth, my perspective on readability and newbies is:

1. The improved readability of the given example is purchased at the price
of understanding the "readability" code. This perhaps isn't a severe
shortcoming if the readability definitions become commonly
accepted/understood, a la "\" and "{}" pairs. I doubt that newbies would
readily understand the readability definitions, thus making the code look
prettier but not necessarily more readable.

2. I didn't find the original definitions all that difficult to understand,
although the "prettying up" via tabs was a (minor) improvement. Perhaps it
is just a matter of choosing a more representative example.

3. I tend to agree with Chuck Moore (always a good thing to do) that the
most important thing to improve code understanding is providing a
description of the problem to be solved (as a minimunm) and the
implementation approach, algorithms, etc. if they are in some way unique or
pertinent. Once the problem is well-understood, coding isn't that much of
an issue. In trying to understand my old code, I have found that my coding
style (and readabilty) have varied widely over the years, but comments
describing the problem and algorithms were always the most useful part of
the code. These are useful even (especially?) when I try to read source
code for a language in which I am not proficient (e.g., C, C++ and VB).

4. Any new language has its own "readability" learning curve that is highly
dependent on the background of the person learning the language. Constructs
and concepts that may seem foreign at first are immediately recognizable and
familiar later on. For example, I can now understand and translate most C
and C++ programs to (Swift) Forth, but only after several years of studying
and asking questions about C syntax, programming methods and constructs. I
have little difficulty understanding most Forth code, after many years of
experience, especially code written by experienced programmers (they usually
leave better tracks).

5. The most commonly-cited difficulties in understanding Forth are often
straw men. Chuck Moore once observed that anyone who couldn't quickly grasp
concepts such as RPN and stacks was going to have difficulties regardless of
the language (not a direct quote, just the gist of it). The same is true,
for example, of understanding the use of pointers and structures in C or
classes in C++. These are concepts that take a little effort to understand
and then are not a consideration afterward.

6. What I see most often is a desire an the part of newbies to change Forth
into a language that they understand rather than accepting it "as is"
(whatever that means). Because Forth is so malleable, it is tempting to add
familiar constructs from other languages. CASE is a case in point (just had
to get that in somehow).

I hope the above is not misunderstood: I realize that the comments may not
directly apply to the effort to improve readability and documentation.
Readability improvements, especially as presented by someone as experienced
as Charles Melice, do not necessarily address the problems encountered by
newcomers to Forth.

-----Original Message-----
From: Richard Owlett [mailto:rowlett_at_atlascomm.net]
Sent: Wednesday, December 04, 2002 12:48 PM
To: sftalk_at_forth.com
Subject: [sftalk] Documenting Forth code was [ Re: Technics to improve
(?) the sources readability.]

[ Cautionary note, this is influenced by recent discussion on
comp.lang.forth concerning mental blocks to learning to program and
learning to program in FORTH in particular. It also reflects the
problems a 'newbie' has with what seems to be a prevailing practice in
commenting code. { further caution -- reflects view of EXACTLY ONE
newbie ;} ]

My problems with the post and the code ( intermixed as they are
related )

1. Just what is the intent of the code?
   a. Is it to insert a TAB to col 43 if MSG>VIEW is encountered in
input stream?
   b. Is part of example related to " * with {} " missing?

2. What is " (later) " trying to accomplish
   A. as a SIDE-ISSUE --- How should one refer to a FORTH word as the
subject of a sentence? In normal writing the " and/or ' serves. BUT,
these have explicit meanings in FORTH.

3. How would these code fragments be used? On what would the be used?
Charles Melice wrote:
>
> I'm searching for technics to improve the sources
> readability.
>
> Is there some other system to propose ?
>
> Charles
>
> \ ----------------------------------------------------
> \ Prefix operator { } to improve source readability.
> \ ... but break the comment {, replaced with {*
> \ ----------------------------------------------------
>
> REQUIRES STACKS
>
> 16 STACK (post-stack)
>
> : (later) ( -- )
> (post-stack) TOP (post-stack) POP
> state @ If compile, Else execute Then ; immediate
>
> : {* postpone { ; \ save it
>
> : { ( "name" -- )
> ' (post-stack) PUSH
> ['] (later) (post-stack) PUSH ; immediate
>
> : } ( -- )
> (post-stack) TOP (post-stack) POP execute ; immediate
>
> \\ {* program text samples (cannot interpret) *}
>
> * without {}
>
> : OnInitDlg ( -- )
> HWND 99 GetDlgItem >R
> R@ FCV_SET_PROJECTION 0 MSG>VIEW drop
> R@ FCV_ADD_OBJECT CreateCube MSG>VIEW drop
> R@ FCV_SET_RENDMODE 2 MSG>VIEW drop
> R@ FCV_VIEW_KEY 0 MSG>VIEW drop
> R> drop ;
>
> * without {}, improved presentation
>
> : OnInitDlg ( -- )
> HWND 99 GetDlgItem >R
> R@ FCV_SET_PROJECTION 0 MSG>VIEW drop
> R@ FCV_ADD_OBJECT CreateCube MSG>VIEW drop
> R@ FCV_SET_RENDER_MODE 2 MSG>VIEW drop
> R@ FCV_VIEW_KEY 0 MSG>VIEW drop
> R> drop ;
>
> * with {}
>
> : OnInitDlg ( -- )
> { GetDlgItem HWND 99 } >R
> { MSG>VIEW R@ FCV_SET_PROJECTION 0 } drop
> { MSG>VIEW R@ FCV_ADD_OBJECT CreateCube } drop
> { MSG>VIEW R@ FCV_SET_RENDER_MODE 2 } drop
> { MSG>VIEW R@ FCV_VIEW_KEY 0 } drop
> R> drop ;
>
> : CB-GetSelText ( id buf -- flag )
> dup off
> over { SENDMSG ( id) CB_GETCURSEL 0 0 }
> dup 0< IF 3drop FALSE EXIT THEN
> >r >r { SENDMSG ( id) CB_GETLBTEXT r> r> swap } -1 > ;
>
> ----------------------------------------------------------------------
> sftalk_at_forth.com The SwiftForth programming discussion email list
> To unsubscribe, send subject "unsubscribe sftalk" to listar_at_forth.com
> For help with listar commands, send subject "help" to listar_at_forth.com
> Archives are located at http://www.forth.com/sftalk -- check them out!
> Search the archives! Visit http://www.forth.com/search for details.
----------------------------------------------------------------------
sftalk_at_forth.com The SwiftForth programming discussion email list
To unsubscribe, send subject "unsubscribe sftalk" to listar_at_forth.com
For help with listar commands, send subject "help" to listar_at_forth.com
Archives are located at http://www.forth.com/sftalk -- check them out!
Search the archives! Visit http://www.forth.com/search for details.
----------------------------------------------------------------------
sftalk_at_forth.com The SwiftForth programming discussion email list
To unsubscribe, send subject "unsubscribe sftalk" to listar_at_forth.com
For help with listar commands, send subject "help" to listar_at_forth.com
Archives are located at http://www.forth.com/sftalk -- check them out!
Search the archives! Visit http://www.forth.com/search for details.
Received on Wed Dec 04 2002 - 15:20:32 PST