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

[Benoît Minisini]

Le 20/02/2014 16:11, Tobias Boege a écrit :
> 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.
>

I'm always happy when somebody else than me does the job. :-)

I think there are two types of example: one that shows a specific 
feature (usually a small project), and the other that is almost a true 
program (for example a little notepad, or a game).

Knowing how to write them is mainly a matter of common sense: they must 
be readable by everyone. So everything must be in english (no choice, 
sorry. Next century, everything will be in chinese, if humanity still 
exists), accurately commented. Identifier should be carefully chosen, so 
that the code is almost "auto"-commented...

In other words, go on!

-- 
Benoît Minisini