[Gambas-user] Restructuring the official Gambas examples

[Benoît Minisini]

Le 28/04/2013 19:30, Tobias Boege a écrit :
> Hi folks,
>
> I'm finally going to write my last A level exam tomorrow. Except the oral
> exam in June, I have ca. 5 months of spare time until matriculation. Among
> working here and there, I plan to do much work on my Gambas components and
> stuff and wanted to start by restructuring the Gambas examples next week.
>
> Hans and I had the feeling that, them likely being the first code a newbie
> will seriously attempt to learn Gambas from (at least that's what I did six
> years ago), they are not too well-suited for that purpose. (Well, I was 12
> back then and my brain was still fresh :-))
>
> Most of them are poorly commented, contain commented-out code for whatever
> features (or just dead code), violate the Gambas naming conventions or
> (this is a point Hans put forward which I not necessarily support) contain
> a bulk of code which just adds a feature but is not really related to
> teach how to use the particular component for which it is an example
> (particularly, he refers to MapView's zooming functionality).
>
> The suggestion is *not* to make a heavily-commented tutorial out of each
> example or to remove extra features, but to split examples into niveau
> stages so that newbies know where they have to expect what extent of
> commentary or additional complexity and that our sort can be more sensible
> of how to write an example to be put upstream.
>
> Look at the Games category. Nobody wants a game (example) to have source
> code where every detail of the used component or the Gambas language is
> explained. I can just tell from my Pong example that these kinds of programs
> tend to get quite complex and the most interesting thing is the game logic
> and the OOP implementation - for experienced programmers.
>
> On the other side are things like in the Basic category which may benefit
> from one or two explanatory comments about what is going on behind the
> scenes and what is to expect from, e.g. attaching an object to an observer
> (this is actually done quite well in ArrayOfControls but with *some little*
> room for improvement).
>
> Hans also suggested, again without me tremendously backing that idea, that
> Benoit lay down rules to which new examples must stick. I just want to
> spread the idea here, nevertheless since my intuition may be wrong at this
> point. Loose guidelines for how to classify a piece into the niveau levels
> would be my approach here.
>
> All in all, my plan would, in the first instance, just be to introduce
> different niveau levels to the examples followed by the consequent change to
> the way in which the IDE presents examples by default. The topic categories
> will remain! - there's just an alternate view of them in niveau levels. On
> the way, I will try my best to remove the grievances from the source code
> and later look at this more closely. But only if Benoit gives his "OK" and
> you guys have also nothing serious to amend.
>
> Regards,
> Tobi
>

I have never found the time to write good examples so you have my full 
blessing.

Just don't work directly on the current examples 
(/trunk/examples/example). Just create a new directory 
('/trunk/examples/src' for... example) where you will store all the 
example projects, with the structure you want. Once done, I will modify 
the IDE to point at the new structure.

Regards,

-- 
Benoît Minisini