[Gambas-user] Restructuring the official Gambas examples

[Tobias Boege]

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