[Gambas-user] Restructuring the official Gambas examples

[Tobias Boege]

On Mon, 29 Apr 2013, Bruce wrote:
> On Sun, 2013-04-28 at 19:30 +0200, Tobias Boege wrote:
> > Hi folks,
> > 
> > {lots} 8<
> 
> Hi Tobi,
> 
> Here's some "opinion", so take it as such and not criticism.
> 

Too bad, for criticism helps to improve our ideas. Now you leave the work to
me to make criticism out of your opinions ;-)

> 1) Who uses the examples and why?  
> I would say there are two general categories of people who access the
> examples. New gambas coders looking for answers to syntax and
> algorithmic questions and experienced coders looking for code they have
> forgotten how to use (I can confirm there is definitely at least one of
> the second type!). The examples need to address both these audiences.
> 

Matti already did sort of that observation. Niveau levels may therefore
actually be too much of a classification. Dividing into newbie and
experienced coder may be closer to the immediate needs.

This could simplify the visual problems of presenting that new view to
some extent.

> 2) Avoiding a plethora of examples
> Although having an example focus on a single aspect of gambas is
> laudable we do not want to end up with a huge set of examples where one
> has to load example B to understand example A, and then example C, D, E
> etc. Any code or feature of an example should be completely self
> contained.
> 

Absolutely true. We don't have any need for an example for each of the
language functions either. That's for the wiki or so.

An example depicts one topic. Right.

> 3) Comments
> A sparsely commented class is worse than no comments at all. By this I
> mean that comments in example code should go beyond the focus of the
> example whenever obscure intent, algorithm or syntax is involved.  If
> not, the naive user is left wondering what that piece of the example
> code does and how and the experienced user, who may be reviewing the
> code because they know that an obscure construct is demonstrated there,
> is again frustrated because that exact bit is not commented.
> There is no such things as too many or too detailed comments. Oh, how I
> know this when having to go back into code I wrote a year, month, week
> ago!
> 

I disagree on that point. I can imagine too many or to detailed comments. My
plans are to comment the "what" and "why" because the "how" should be
obvious from the code. Otherwise it's bad code.

Regards,
Tobi