Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search

[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 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 . I wonder how long it would take to get such a script completely notated... Quoting Paavo Nevalainen <>: