[Gambas-user] Norming official examples (reloaded); was: Submitting "Example" Candidates

[Tobias Boege]

On Wed, 19 Feb 2014, Beno?t Minisini wrote:
> Le 19/02/2014 02:09, Louis W. Adams, Jr. a ?crit :
> > What is the best way to submit a GAMBAS program to be considered as an
> > example for beginner programmers?  I have a simple program to offer, which
> > shows how to do a few basic things that I struggled with while learning
> > GAMBAS.  (I'm still learning.)  It generates random colors and sorts them by
> > hue on a 2D color chart, and is based on my color science research.  Here is
> > a sample output image:  test.png
> > <http://gambas.8142.n7.nabble.com/file/n45773/test.png>
> >
> > The program also demonstrates the speed of GAMBUS programs.  The above image
> > was created from over 32,000 colors in a fraction of a second.
> >
> > The main lesson of the example is how to construct a picture using graphics
> > commands, display the picture in a display area control, and export the
> > picture to a file.  Another lesson is how to split up the construction of
> > one picture into several subroutines.  Most of the other examples I've seen
> > that did these things were too complicated for me as a beginner to follow!
> >
> > Lou
> >
> 
> Hi,
> 
> A good example should be well written, and all identifiers and comments 
> should be in english. (Alas I'm not sure this is the case for all 
> current examples).
> 

Ok, ok... I get a worse conscience every time someone talks about examples.
If you don't mind (do you, Benoit? - regarding your release schedule, etc.?),
I'll commit my attempt at norming the current examples with respect to these
four points:

 1. adherence to the naming conventions and coding style;
 2. proper formatting and usage of spaces [ IIRC, this is also a concern of
    Kevin :-) ];
 3. including commentary where and only where necessary and
 4. concentrating on the educational purpose

but it's not complete yet, also because I have no idea about some of the
examples (like DBus or the no-at-all-so-simple MySQLExample).

*Or does anyone have objections against norming examples?*

For reference, my decisions for the points above were guided by:

 1. http://gambasdoc.org/help/doc/naming?v3;
 2. common sense with a little bit of MHO;
 3. the "document *what*'s done and not how" and "as few as possible, as
    much as necessary" mantras and
 4. MHO (don't worry about this point; IIRC, I haven't deleted any quality
    of any project but condensed and re-structured it *where possible*)

I just write these down so I don't have to include them into the commit
log. If these guidelines are accepted - you get a teaser with the
Basic/Object example as an attachment - I'll write them down into an
article on gambasdoc.org about code guidelines for submitting official
examples.

Regards,
Tobi

PS: Please don't repeat yourselves, as I'm aware of the opinions from
    http://sourceforge.net/mailarchive/message.php?msg_id=30780142.

-- 
"There's an old saying: Don't change anything... ever!" -- Mr. Monk
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Object-3.3.90.tar.gz
Type: application/octet-stream
Size: 45 bytes
Desc: not available
URL: <http://lists.gambas-basic.org/pipermail/user/attachments/20140220/371e3b3b/attachment.obj>