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.
Received on Wed Dec 04 2002 - 12:46:46 PST