[REBOL] Re: Personal Programming and Rebol Promotion
From: nick1:musiclessonz at: 22-Dec-2007 23:24
Hi Paavo,
Just tonight, a reader from my site wrote to say that in the past, all
the documentation he had previously read had led him to misunderstood
the syntax of a simple 'if expression, originally thinking that the
conditional evaluation needed to be placed in brackets (which made
every condition always evaluate to true...). Even things like that
can be tripping blocks for newcomers, so I agree that obfuscated code
can be totally unfathomable.
With that said, it is important to recognize common code patterns and
Rebolisms that are fast and short in expression, even if they're hard
to read at first. I don't know that common (more difficult to read)
syntax necessarily needs to be avoided and replaced with obvious
patterns. (If they're common, they _should_ be internalized).
Instead, what I missed in the beginning with Rebol was more documented
examples ... I mean the kind of detailed, line by line documentation
needed to understand each expression, as well as the overall structure
of a script.
I love the idea of maintaining a collection of useful, classic
programs that demonstrate common techniques and solutions to typical
problems and situations. Having a clear English language
translation/explanation of any code, no matter how unreadable, can
make it much more friendly to digest and internalize. If I were to
put forth the effort, instead of rewriting examples to make them more
readable, my suggestion would be to just write lots of more detailed
explanation - LOTS more.
Anyone interested in making Rebol more accessible to others could
potentialy help by adding detailed documentation to scripts that are
in the public domain. Anytime someone has an "aha" moment,
understanding how a certain expression or code pattern works, in the
example where it occurred, notating that realization would undoubtedly
help others down the road... I'm sure that line-by-line explanations
of more code from rebol.org would help average new users dramatically.
Anyone can help with that sort of thing - and the wiki sites are
great resources for creating repositories of analyzed and notated code.
If anyone is interested in starting a project like that, we just need
to copy over a few scripts to a chosen wiki, and add our own comments.
As an example, I put Frank Sivertson's Rebtris, up at
http://en.wikibooks.org/wiki/REBOL_Programming/Examples . I wonder
how long it would take to get such a script completely notated...
Quoting Paavo Nevalainen <Paavo.Nevalainen-saunalahti.fi>:
